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
