Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Message-ID: <41A42E18.1030402@apache.org>
Date: Wed, 24 Nov 2004 16:45:44 +1000
From: David Crossley <crossley@apache.org>
User-Agent: Mozilla Thunderbird 0.9 (Macintosh/20041103)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: [Proposal] review of sitemap component documentation
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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.

--David