RE: [VOTE] Consensus about documentation location - revised version

["Linden H van der (MI)" <H....@MI.unimaas.nl>]

Based on some comments I would like to revise the proposal. Let's focus
first on what info goes where and what the general direction will be. 
As things progress, we can focus on explicit processes and, given the
current discussion, the roles/rights.

- the current Daisy site at the zones [1] will be the "incubator" for
the new documentation. I.e. new content is to be entered there.

- this documentation is targeted at Cocoon 2.1. This means that we try
to write version-independent documentation, but when there is a
difference between 2.1 and 2.2, the documentation will describe 2.1. If
possible, notes will be added describing the difference in 2.2 or at
least that there IS a difference in 2.2.
[Note: I was under the impression that 2.2 was already close to a
release-able state]

- the rules for the various roles have been defined already [2]. Note,
registered guests can leave comments.

- this also implies that we stick with Daisy as CMS (and not venture on
the endless hunt for THE best system/toolset).

- all current content in both wiki and "official docs" will be evaluated
and either deprecated or moved over into the Daisy site. I.e. reducing
the wiki to random thoughts and proposals. 

- it should be possible to easily add new documentation contributions to
the Daisy site, although it should be separated from the current site so
editors/publishers can review the information before adding it to the
documentation. This is not a vote of "mistrust", but rather an effort to
keep the documentation under control. AND, as stated: guest contributors
may feel very proud if their contribution is incorporated in the
"official" docs. I know I was proud when my first patch was picked up
and committed.
[Note: this means that a separate site with different roles/rights has
to be set up]

- we should make sure that we end up with only one (virtual)
documentation site, whatever the format/system etc. will be. The current
intention is to eventually move the content of the Daisy site over to
the "official documentation". 
[Note: API docs provide a special set of generated documentation. They
serve a different purpose than the "ordinary" documentation. To me, at
least for now, it is sufficient if there is an easy link from the
"ordinary" docs to the API docs, even if they reside in a different
location.]

- Extraction of "current state" for inclusion in a release should be
possible. AFAIU there is a Daisy-to-Forrest plugin available (soon). 


[1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html
[2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html

Bye, Helma

Re: [VOTE] Consensus about documentation location - revised version

[Ralph Goers <Ra...@dslextreme.com>]

Linden H van der (MI) wrote:

>Based on some comments I would like to revise the proposal. Let's focus
>first on what info goes where and what the general direction will be. 
>As things progress, we can focus on explicit processes and, given the
>current discussion, the roles/rights.
>
>- the current Daisy site at the zones [1] will be the "incubator" for
>the new documentation. I.e. new content is to be entered there.
>
>- this documentation is targeted at Cocoon 2.1. This means that we try
>to write version-independent documentation, but when there is a
>difference between 2.1 and 2.2, the documentation will describe 2.1. If
>possible, notes will be added describing the difference in 2.2 or at
>least that there IS a difference in 2.2.
>[Note: I was under the impression that 2.2 was already close to a
>release-able state]
>
>- the rules for the various roles have been defined already [2]. Note,
>registered guests can leave comments.
>
>- this also implies that we stick with Daisy as CMS (and not venture on
>the endless hunt for THE best system/toolset).
>
>- all current content in both wiki and "official docs" will be evaluated
>and either deprecated or moved over into the Daisy site. I.e. reducing
>the wiki to random thoughts and proposals. 
>
>- it should be possible to easily add new documentation contributions to
>the Daisy site, although it should be separated from the current site so
>editors/publishers can review the information before adding it to the
>documentation. This is not a vote of "mistrust", but rather an effort to
>keep the documentation under control. AND, as stated: guest contributors
>may feel very proud if their contribution is incorporated in the
>"official" docs. I know I was proud when my first patch was picked up
>and committed.
>[Note: this means that a separate site with different roles/rights has
>to be set up]
>
>- we should make sure that we end up with only one (virtual)
>documentation site, whatever the format/system etc. will be. The current
>intention is to eventually move the content of the Daisy site over to
>the "official documentation". 
>[Note: API docs provide a special set of generated documentation. They
>serve a different purpose than the "ordinary" documentation. To me, at
>least for now, it is sufficient if there is an easy link from the
>"ordinary" docs to the API docs, even if they reside in a different
>location.]
>
>- Extraction of "current state" for inclusion in a release should be
>possible. AFAIU there is a Daisy-to-Forrest plugin available (soon). 
>
>
>[1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html
>[2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html
>
>Bye, Helma
>
>  
>
+1

Re: [VOTE] Consensus about documentation location - revised version

[Glen Ezkovich <gl...@hard-bop.com>]

On Jun 13, 2005, at 10:16 AM, Linden H van der (MI) wrote:

> Based on some comments I would like to revise the proposal. Let's  
> focus
> first on what info goes where and what the general direction will be.
> As things progress, we can focus on explicit processes and, given the
> current discussion, the roles/rights.
>
> - the current Daisy site at the zones [1] will be the "incubator" for
> the new documentation. I.e. new content is to be entered there.
>
> - this documentation is targeted at Cocoon 2.1. This means that we try
> to write version-independent documentation, but when there is a
> difference between 2.1 and 2.2, the documentation will describe  
> 2.1. If
> possible, notes will be added describing the difference in 2.2 or at
> least that there IS a difference in 2.2.
> [Note: I was under the impression that 2.2 was already close to a
> release-able state]
>
> - the rules for the various roles have been defined already [2]. Note,
> registered guests can leave comments.
>
> - this also implies that we stick with Daisy as CMS (and not  
> venture on
> the endless hunt for THE best system/toolset).
>
> - all current content in both wiki and "official docs" will be  
> evaluated
> and either deprecated or moved over into the Daisy site. I.e. reducing
> the wiki to random thoughts and proposals.
>
> - it should be possible to easily add new documentation  
> contributions to
> the Daisy site, although it should be separated from the current  
> site so
> editors/publishers can review the information before adding it to the
> documentation. This is not a vote of "mistrust", but rather an  
> effort to
> keep the documentation under control. AND, as stated: guest  
> contributors
> may feel very proud if their contribution is incorporated in the
> "official" docs. I know I was proud when my first patch was picked up
> and committed.
> [Note: this means that a separate site with different roles/rights has
> to be set up]
>
> - we should make sure that we end up with only one (virtual)
> documentation site, whatever the format/system etc. will be. The  
> current
> intention is to eventually move the content of the Daisy site over to
> the "official documentation".
> [Note: API docs provide a special set of generated documentation. They
> serve a different purpose than the "ordinary" documentation. To me, at
> least for now, it is sufficient if there is an easy link from the
> "ordinary" docs to the API docs, even if they reside in a different
> location.]
>
> - Extraction of "current state" for inclusion in a release should be
> possible. AFAIU there is a Daisy-to-Forrest plugin available (soon).
>
>
> [1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html
> [2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html
>
> Bye, Helma
>

My non-voting +1

>


Glen Ezkovich
HardBop Consulting
glen at hard-bop.com



A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to  
worry about answers."
- Thomas Pynchon Gravity's Rainbow

Re: [VOTE] Consensus about documentation location - revised version

[Bertrand Delacretaz <bd...@apache.org>]

Le 13 juin 05, à 17:16, Linden H van der ((MI)) a écrit :

> Based on some comments I would like to revise the proposal...

I'm fine with everything you suggest, just a few comments below.

> ...- this documentation is targeted at Cocoon 2.1. This means that we 
> try
> to write version-independent documentation, but when there is a
> difference between 2.1 and 2.2, the documentation will describe 2.1. If
> possible, notes will be added describing the difference in 2.2 or at
> least that there IS a difference in 2.2...

This is fine assuming there is enough energy to complete the task in 
due time.
It might be safer to focus on 2.2, with the aim of being ready when 2.2 
is released. But whoever does the job gets to decide, if you guys think 
the above plan is workable, all the better. FWIW, I will do my best to 
contribute by reviewing docs, but won't be able to do any or much 
actual writing in the next few months.

> ...[Note: API docs provide a special set of generated documentation..

This will hopefully not only be the API docs, but the components docs 
as well (Generators, Transformers, Serializers etc.).

If the cocoon-refdoc project [1] works out as I hope (but I have no 
idea yet if it will), we'll be able to generate "manpage-like" docs 
with essential information, snippets of code, etc., in an XML format 
suitable for inclusion in Forrest or Daisy docs.

Don't hold your breath, but as you indicate it is good to keep that in 
the back of your minds, and maybe start working on the more general 
docs first, assuming the details will come from the generated reference 
docs.

-Bertrand

[1] http://wiki.apache.org/cocoon/CocoonRefDocProject



P.S. Helma, it seems like your mailer is breaking threads sometimes, 
but not always. For example, [2] starts a new thread although it is 
obviously a reply to [3]. If it's easy to fix it might be good for our 
archives.

[2] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111866680601135&w=2
[3] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111866271205873&w=2