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 >> 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... -- "The heights of genius are only measurable by the depths of stupidity."
