cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hepabolu <hepab...@gmail.com>
Subject Re: 2.2 Documentation
Date Wed, 23 Nov 2005 11:58:02 GMT
Regarding the documentation of 2.2:

Let me first give you some Daisy background to clarify things, before I 
explain what I have in mind.
Note that this is the quick & dirty explanation. The Outerthought boys 
can give a much more detailed overview.

Daisy supports "sites" (the already mentioned Legacy docs and 
Documentation) and "collections". A collection is merely a set of 
documents and a site can be considered as a view on one or more 
collections. That's what is currently the case in our Daisy setup in the 
zones:

Collection "legacydocs" contains all documentation as it was present in 
the xdocs of BRANCH_2.1.X. Collection "documentation" contains all new 
documents that are written in Daisy.
Bruno has marked documents part of "legacydocs" with a two line red 
warning at the top of the document. You can see this when you open such 
a page in Daisy.

There are already two sites in Daisy: Legacy docs and Documentation. 
Both use documents from both collections.

My idea was this:

I've used Legacy docs site to recreate the "old" cocoon.apache.org site 
as best as possible. If this is not enough, a little bit of work needs 
to be done.
This site will be restricted to the 2.1 branch. Since Cocoon 2.1 is 
frozen when it comes to new features, I suggest that the documentation 
is only updated when some blatant errors or typos are found.

For the 2.2 version please use the Documentation site. That's where new 
documentation is supposed to be entered. This site also contains links 
to all available documents in the legacydocs collection, see the last 
line in the navigation bar.
This is added for convenience: if you find documentation in the 
legacydocs that is still valid for the 2.2 version, just move the 
documentation from the legacydocs collection to the documentation 
collection. This has no impact on the documentation in the Legacydocs site.
I know it's possible that a document resides in both collections, but I 
want to end up with a collection of legacydocs that holds information 
that is either completely outdated or only valid for the 2.1 branch.

I know we can make branches in Daisy, but at the moment I don't think 
this is necessary. I'd rather use that feature when we move from 2.2 to 3.0.

In summary:
- don't use the legacydocs site

- new documents, about new features of Cocoon 2.2, go into the 
Documentation site. They are part of the documentation collection 
(automatically if you have the Documentation site open) and they are of 
type "Document" (not SimpleDocument).

- if the documentation you want to write is already present in the 
legacydocs and is valid for both versions, move the document to the 
"documentation" collection:
    - select the document, select "edit" (you have to be logged in), 
select the "Misc" tab and make sure the "selected" list contains only 
"documentation".

- if the documentation you want to write is already present in the 
legacydocs, but is not entirely correct:
    - are the changes you want to add also valid for 2.1?
       - yes: go ahead, change the document and move it from the 
legacydocs to documentation.

       - no: are the changes minor?
             - yes: add one or more "notes" (paragraphs marked Note) 
that explain the differences between 2.1 and 2.2 and move the document 
from the legacydocs to documentation.

             - no: create a new document in the documentation collection 
and write the information as if the legacydocs document didn't exist.

- if you find documentation in the legacydocs that is outdated for both 
2.1 and 2.2, then retire the document (Misc tab, under the Options section)

- if you find documentation in the wiki that is useful:
    - copy the information to a Daisy document and finish this
    - mark the wiki page with a message that the information is added to 
the "official" Cocoon documentation.

- if there is information in the mailing lists that is useful:
    - copy the information and elaborate it, turn it into a coherent 
piece of information.
    - if necessary, add the links to the relevant messages (each Daisy 
document has a separate links section that ends up at the bottom of the 
page). PLEASE DON'T SIMPLY REFER TO THE MAIL MESSAGES.

Most of this info is also written on the home page of the Cocoon 
Documentation site in Daisy:

http://cocoon.zones.apache.org/daisy/documentation/659.html

If the above is clear, I'll update that page to reflect this information.

Bye, Helma


Mime
View raw message