On Friday, November 15, 2002, at 03:52 AM, Bertrand Delacretaz 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.
I don't see how a strict DTD will really produce good doc content. I developed a howto dtd for Forrest (based on document-v11) and ended up leaving many elements optional (based on good advice from Steven and others). I think well-written guidelines and good examples (and editing) are key.
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.
Well, if the effort needed was granular enough, we might get more help/resources. It can be really difficult to write a comprehensive doc about Cocoon because so many concepts/skills are involved. If someone knows a lot about a specific topic (but not necessarily others), they could contribute that content and then a more advanced user could weave them together into meaningful tracks. If we can break it into small pieces, it might happen.
Diana
