cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: Documentation Format...
Date Sat, 16 Nov 2002 12:20:19 GMT

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.


View raw message