cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen ...@hist.umn.edu>
Subject Re: Documentation Format...
Date Fri, 15 Nov 2002 18:48:40 GMT
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



Mime
View raw message