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 etc... Problem is, do we have the resources for what could be a major restructuring of the docs, including DTD design? The fairly slow activity on the -docs list makes me a little wary of starting big documentation projects, as lack of resources might cause them to fail. Would you or your team be able to contribute to this "docs refactoring" project? -Bertrand
