cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: Documentation Format...
Date Tue, 19 Nov 2002 18:11:47 GMT

Andy Lewis wrote:
> I've been hammered for the last couple of days - so I'm just now catching back up here,
> bear with me...
>>On Friday, November 15, 2002, at 03:52  AM, Bertrand Delacretaz wrote:
> <snip/>
>>>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
>>editing)  are key.
> I actually agree - a strict DTD isn't needed. I am far more interested in a general defination
> what should be there - what sections, and what they should have. A guide to authors is
> more effective at this point, since not everyone can read DTDs well anyway

Anakia hasn't enforced a DTD, and we find ourselves with docs that tend 
to leak into style rather than content.

A DTD, being a tool, has nothing to do with good doc content. It can be 
used to produce more consistent output, remain focused on content rather 
than style and so on, but can itself create no good doc content, of course.

>>>Problem is, do we have the resources for what could be a major
>>>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
>>involved. If someone  knows a lot about a specific topic (but not necessarily others),
>>could contribute that content and then a more advanced user could weave  them together
>>meaningful tracks. If we can break it into small  pieces, it might happen.
> Granular effort, and incremental progress. "Big Bang" projects are always higher risk
than slow
> progress. So what if it takes severla releases to get all of it done? Done wel, each
> documented will make a huge improvmeent in the ability of people to understnad and use
> component. And I think there is a stronmg liklihood that there will be a "critical mass"
point on
> this kind of effort where there will be a lot more help from componenet writers and developers
> such...

+1 Witness the Wiki.

Nicola Ken Barozzi         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message