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
