You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by Nicolas Maisonneuve <n....@gmail.com> on 2005/04/12 19:44:30 UTC
State of the documentation effort
Hy,
I would like to know the state of the documentation effort.
Actually I'm afraid that after the development the new documentation
system (another excuse for not beginning the documentation ;-)) ,
there won't be a real effort to build a new documentation (= all
committers will stop to code et will create a good documentation)
Nicolas
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 13 avr. 05, à 05:15, Sebastien Arbogast a écrit :
> Ok thanks for the information I didn't know that. I supposed that docs
> mailing list was for discussion regarding documentation effort...
It was when it was created, but we felt that separating the (mostly
inexistent) "docs team" from the rest didn't help, and decided to move
docs discussion to dev@
-Bertrand
Re: State of the documentation effort
Posted by Sebastien Arbogast <se...@gmail.com>.
Ok thanks for the information I didn't know that. I supposed that docs
mailing list was for discussion regarding documentation effort and so
I just wanted to explain why it was worth discussing that out of this
list. But obviously I was wrong.
Anyway I've subscribed to all Cocoon lists to see if I can help as I'm
really willing to.
On 4/12/05, David Crossley <cr...@apache.org> wrote:
> Sebastien Arbogast wrote:
> >
> > And this is a debate that would fit both dev and doc mail lists as
> > it's a matter of coordinating both kinds of efforts.
>
> We don't discuss on the "docs" mailing lists.
> Its purpose is supposed to be for the Wiki diff
> autmoted notifications.
>
> The docs discussion is happening on the "dev" list.
>
> --David
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: users-help@cocoon.apache.org
>
>
--
Sebastien ARBOGAST
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by David Crossley <cr...@apache.org>.
Sebastien Arbogast wrote:
>
> And this is a debate that would fit both dev and doc mail lists as
> it's a matter of coordinating both kinds of efforts.
We don't discuss on the "docs" mailing lists.
Its purpose is supposed to be for the Wiki diff
autmoted notifications.
The docs discussion is happening on the "dev" list.
--David
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Sebastien Arbogast <se...@gmail.com>.
As a Cocoon newbie, I totally share your concerns but I'm not sure
that it is necessary to stop coding while writing documentation. But
it would be great if there were two teams, one for coding the next
version and one for writing the documentation, with a few Cocoon
experts (the ones who know the system the best) to synchronize efforts
between both teams. Or even for each block for example, there could be
coders and documenters working in parallel and talking with each other
to keep documentation and code in sync.
But whatever the solution I think that the key is organization
(something that is not easy to achieve in Open Source projects :oS )
and that one should avoid alternating coding and documenting because
documenting is (by experience) not very agreeable, and all the less so
when you have to write new documentation for great bunches of code.
And this is a debate that would fit both dev and doc mail lists as
it's a matter of coordinating both kinds of efforts.
But maybe this organization still exists... Does it ?
On Apr 12, 2005 12:44 PM, Nicolas Maisonneuve <n....@gmail.com> wrote:
> Hy,
>
> I would like to know the state of the documentation effort.
> Actually I'm afraid that after the development the new documentation
> system (another excuse for not beginning the documentation ;-)) ,
> there won't be a real effort to build a new documentation (= all
> committers will stop to code et will create a good documentation)
>
> Nicolas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: users-help@cocoon.apache.org
>
>
--
Sebastien ARBOGAST
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Upayavira <uv...@upaya.co.uk>.
Sebastien Arbogast wrote:
> It's always the same paradox : the people who need documentation the
> most, are the ones that are less qualified to participate in its
> writing, otherwise they wouldn't need documentation. For Cocoon
> experts, it's a matter of realizing that you can code marvelous
> features, if nobody can understand them through a coherent and
> accessible documentation, it's totally useless. And when you see
> entire blocks (like apples for example) that don't have any
> documentation...
> So I totally agree : please "skilled people" feel free to participate
> in Cocoon documentation effort... but don't be suprised if we newbies
> are a little... chomping at the bit !
The documentation has needed effort for some time. And together,
Reinhard and myself have started working on a new framework. We've got
some headings worked out, and the technology in place. I'm now in the
process of converting files from one format to another. Once that's
done, we can start moving pages across one by one, then start filling in
the gaps.
That process of moving things across is something that people can help
with. Do subscribe to the developer list and help if you can!
Regards,
Upayavira
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Sebastien Arbogast <se...@gmail.com>.
It's always the same paradox : the people who need documentation the
most, are the ones that are less qualified to participate in its
writing, otherwise they wouldn't need documentation. For Cocoon
experts, it's a matter of realizing that you can code marvelous
features, if nobody can understand them through a coherent and
accessible documentation, it's totally useless. And when you see
entire blocks (like apples for example) that don't have any
documentation...
So I totally agree : please "skilled people" feel free to participate
in Cocoon documentation effort... but don't be suprised if we newbies
are a little... chomping at the bit !
On Apr 12, 2005 1:31 PM, Reinhard Poetz <re...@apache.org> wrote:
> Nicolas Maisonneuve wrote:
> > Hy,
> >
> > I would like to know the state of the documentation effort.
> > Actually I'm afraid that after the development the new documentation
> > system (another excuse for not beginning the documentation ;-)) ,
> > there won't be a real effort to build a new documentation (= all
> > committers will stop to code et will create a good documentation)
>
> Don't worry, having the new documentation system will not mark the end of all
> our efforts. Upayavira has started to integrate the existing docs into the new
> repository so that they can easily be reviewed. After that we will start to fill
> the gaps.
>
> It will take longer than expected (I've had the last weeks less time to work on
> Cocoon than expected when I started with the new doc system, and it won't become
> better by the end of May) but you can be sure that I will bring my work to an
> end - sooner or later ;-)
>
> Well, if this is too slow for somebody, I'm sure that there are many skilled
> people out there that can jump in ...
>
> --
> Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
>
> {Software Engineering, Open Source, Web Applications, Apache Cocoon}
>
> web(log): http://www.poetz.cc
> --------------------------------------------------------------------
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
> For additional commands, e-mail: users-help@cocoon.apache.org
>
>
--
Sebastien ARBOGAST
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Reinhard Poetz <re...@apache.org>.
Nicolas Maisonneuve wrote:
> Hy,
>
> I would like to know the state of the documentation effort.
> Actually I'm afraid that after the development the new documentation
> system (another excuse for not beginning the documentation ;-)) ,
> there won't be a real effort to build a new documentation (= all
> committers will stop to code et will create a good documentation)
Don't worry, having the new documentation system will not mark the end of all
our efforts. Upayavira has started to integrate the existing docs into the new
repository so that they can easily be reviewed. After that we will start to fill
the gaps.
It will take longer than expected (I've had the last weeks less time to work on
Cocoon than expected when I started with the new doc system, and it won't become
better by the end of May) but you can be sure that I will bring my work to an
end - sooner or later ;-)
Well, if this is too slow for somebody, I'm sure that there are many skilled
people out there that can jump in ...
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
Re: State of the documentation effort
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 12 avr. 05, à 19:44, Nicolas Maisonneuve a écrit :
> ...I would like to know the state of the documentation effort...
There's some info at http://wiki.apache.org/cocoon/22NewDocuments,
including a "how can you help" section.
The existing 2.1 docs are being moved to a "legacy" tab in the new docs
(see http://brutus.apache.org/docs/build/cocoon-2-2/), from where they
will have to be reviewed to decide what to keep and how to organize
what is kept.
Just reorganizing the existing docs in an improved structure would be a
big improvement, as very often the information is here, only hard to
find with the current structure.
This is a process where many people can help, without necessarily
needing deep knowledge of Cocoon (and I'm sure specific questions would
get quick answers on the dev@ list).
Also, as explained in
http://wiki.apache.org/cocoon/22NewDocumentsGeneration, one can now run
Forrest locally to see edits immediately, so working on the docs *is*
convenient.
So, there is progress even if its slow, and help is much welcome!
-Bertrand