Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-docs@xml.apache.org
Message-ID: <3DD54188.50706@hist.umn.edu>
Date: Fri, 15 Nov 2002 12:48:40 -0600
From: Tony Collen <tc@hist.umn.edu>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.1) Gecko/20020826
MIME-Version: 1.0
To: cocoon-docs@xml.apache.org
Subject: Re: Documentation Format...
References: <1893.128.159.142.62.1037291025.squirrel@netarcana.com>
 <20021115085229.E084C23CD8@dj.codeconsult.ch>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Bertrand Delacretaz wrote:

>On Thursday 14 November 2002 17:23, Andy Lewis wrote:
>  
>
>>. . .
>>What about a UNIX man page
>>approach to technical docs? For each transformer, gerneator, inputmodule,
>>etc, have a sinlge man page type document with the technical details,
>>samples if any, formats, etc. 
>>. . .
>>    
>>
>
>Makes at lot of sense.  As Cocoon uses many components, it makes sense for 
>the reference docs to follow the pattern, even more once Blocks are here, as 
>each Block will need its own modular documentation.
>
>I think a single FileGenerator page, for example, could include information 
>for both users and developers, assuming a strict page structure (DTD) is 
>adhered to. The "DTD" of unix man pages is certainly a good starting point 
>for this.
>
>This might mean restructuring much of the docs, trying to get obvious URLs 
>like
>
>  docs/components/generators/FileGenerator.html
>  docs/components/serializers/PDFSerializer.html
>
>(and later)
>  docs/blocks/pdf/fop/FopPdfBlock.html
>  
>

+1.  The code is organized logically into packages, why shouldn't the 
docs? :)  


The current docs are "organized", in a sense, in that stuff that goes 
together is sort of globbed together, but I think the project would 
benefit from something more logically organized.

If I go to x.a.o/cocoon looking for help in getting Cocoon speaking to a 
database, do I look in How-To's, Tutorials, or FAQs?  Or in the 
user-guide?  


I've been of the opinion that PHP has the best documentation around, and 
that we should use them as a model for how to do things. Looking at the 
PHP documentation, you'll see that there's more to "documentation" than 
just "how to do things".  There's a quick reference page, as well as a 
"manual".  If PHP came in a box, that's what would be printed and 
included with it.  I hate to say it, but if the current Cocoon 
documentation was converted to print and then thown in the box, the 
first thing I'd do would be throw it out :)    All kidding aside, I 
think we should try to make our docs as professional as possible.  Good 
docs make or break a project.


Tony