cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Helma van der Linden <h.vanderlin...@mi.unimaas.nl>
Subject Re: [RT] doco lite?
Date Tue, 26 Oct 2004 21:36:15 GMT
Upayavira wrote:

>>> GOALS
<snip/>

G4. Make submitting documentation a more straight forward process. I 
haven't yet looked at the ins and outs of the xdocs, but I know from the 
times I tried to find the documentation in the checked out tree that I 
was unable to figure out how it worked.

>>> TOOLS / TECHNIQUES
<snip/>

>> 1)Does all this actually make the documentation any better?
>> 2)Should any effort towards documentation ATM go into improving its 
>> *quality* or improving its 
>> {searchability|updateability|scaleability|auto-generateability}

Unless the proposal will (also) lead to simple way of adding 
documentation (and I'm thinking about only slightly more difficult than 
the wiki), I think this process will result in a technical overhaul 
without improving the quality of the documentation.

> As we discussed at the hackathon, I think both are concerns that 
> interrelate, and effort can be applied separately to either.

True, but, at the moment all discussions about documentation tend to 
sway into the technical area and the actual writing is forgotten.

> As it is, we have a complex system that few people know how to operate. 
> I've written docs, but I've never deployed them to the site. This acts 
> as a dis-incentive to existing and potential documentation writers.

Put them in the wiki! Why haven't you done so, yet? :-)

> Other than that, we have a xdocs system that does work, and a wiki that 
> works. We can use right now to write better docs. We just need to make 
> the effort.

By all means, do implement this proposal if everyone feels it improves 
the infrastructure of the documentation. I will immediately agree to any 
proposal that will simplify the documentation generation process which 
will improve the update frequency.
However, we should also think about how to get the quality of the 
documentation updated and how to encourage potential documentation 
writers to actually sit down and produce the actual text.

Bye, Helma



Mime
View raw message