cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruno Dumon <br...@outerthought.org>
Subject Re: 2.2 Documentation
Date Wed, 23 Nov 2005 19:10:38 GMT
On Wed, 2005-11-23 at 12:58 +0100, hepabolu wrote:
> 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.

Are you sure this is unnecessary? The current setup shares the same
documents in the new docs and the legacy docs. Thus when the new docs
are updated, refactored, retired etc, this influences the legacy docs
too. This was fine as long as the legacy docs served exactly for this
purpose, but now the legacy docs have turned into the official 2.1.8
documentation. If we don't make a branch for 2.1.8, there's no way the
2.1.x docs can still be produced and maintained in the future.

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org                          bruno@apache.org


Mime
View raw message