cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Lewis" <...@ascii27.net>
Subject Re: Documentation Format...
Date Tue, 19 Nov 2002 16:48:28 GMT
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."



Mime
View raw message