Andy Lewis wrote:
I've been hammered for the last couple of days - so I'm just now catching back up here, please 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 (and editing) are key.
I actually agree - a strict DTD isn't needed. I am far more interested in a general defination of what should be there - what sections, and what they should have. A guide to authors is probably 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 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.
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 componenet documented will make a huge improvmeent in the ability of people to understnad and use the 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 and such...
+1 Witness the Wiki.
--
Nicola Ken Barozzi [EMAIL PROTECTED]
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------