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: <41ACDED1.2040305@upaya.co.uk>
Date: Tue, 30 Nov 2004 20:57:53 +0000
From: Upayavira <uv@upaya.co.uk>
User-Agent: Mozilla Thunderbird 0.7 (Windows/20040616)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [Proposal] review of sitemap component documentation
References: <41A42E18.1030402@apache.org>
In-Reply-To: <41A42E18.1030402@apache.org>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

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