cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: [Proposal] review of sitemap component documentation
Date Wed, 24 Nov 2004 06:28:58 GMT
David Crossley wrote:
> The current User Guide documentation has one document
> for each Sitemap Component, e.g.
> http://cocoon.apache.org/2.1/userdocs/generators/file-generator.html
> 
> Each main document has a shell with some content
> in src/documentation/xdocs/userdocs/*
> 
> During the 'build docs' a "SitemapTask' is called.
> This scans the java code and extracts certain javadoc-like
> tags and appends this information to the top of each
> shell document to produce the "Description" and "Info"
> sections.
> 
> We need to consistently review both the shell documents
> and the javadoc-like tags in the code. While we are
> in there, the actual javadoc comments and tags could
> also be reviewed.
> 
> I propose to create a planning document to co-ordinate
> this effort. It would be a table which lists each sitemap
> component and whether each aspect has been reviewed.
> The columns are not yet determined, but they would
> be things like: shell doc present, shell doc suitable,
> javadoc tags present, javadoc tags suitable, etc.
> 
> Then i, and others, can gradually work through the list
> and get each document/tags up-to-date. If we cannot
> readily determine the info, then we would ask pertinent
> questions on the dev list. If that doesn't help then
> we can dig in the 'svn log' to find the culprits.
> 
> This is something that i have been wanting to do for
> ages and with the recent brouhaha about documentation,
> i thought it finally time to get started. It is going
> to be a long road.
> 
> If no-one says stop, then i will just commence soon.

Go for it!

We also have to consider that we have more independant blocks very soon, means 
that we have the goal that each block can be released seperatly and IMO it 
should provide its own docs.

This seems to be the simple part. More difficult is providing a complete 
documentation consisting of Cocoon core and all blocks automatically ...

-- 
Reinhard

Mime
View raw message