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.
Have any docs actually been done with this process? I'm curious to find out more about how what the conversion actually does. (I guess I could just try it, but then, that would be too easy!)
Regards, Upayavira
