OpenSource documentation problems

[Steve Holden]

Terry Hancock wrote:
> On Wednesday 31 August 2005 07:05 pm, Michael Sparks wrote:
> 
>>When people complain /in here/ about the documentation not being perfect for
>>python I personally find it sad and ironic. It's sad because it says to the
>>person who spent their time (when they could be doing something else) that
>>they wasted it, the docs are worthless etc - when they clearly *haven't*
>>wasted their time and the docs are worthwhile. It's ironic though because
>>they're criticising themselves. After all they understand how the docs can
>>be better and the docs are shared. Unless they contribute back they're
>>actually attacking themselves as much as the person who "wastes" their time
>>writing "worthless" docs.
> 
> 
> There is one criticism however, which I think is valid, which could
> be fixed, and which would probably leverage community effort better:
> it could probably be a lot easier to contribute to the documentation.
> 
> I haven't attempted it myself, but my understanding is that there
> is something of a learning curve to producing documentation using
> the docutils.  This has the effect of excluding anyone from
> contributing who is not willing to overcome that learning curve.
> 
> In order to make that tradeoff worthwhile, the potential contributor
> must have a pretty serious objection to the documentation and/or a
> fairly large amount of changes that they want to make. Furthermore,
> they have to have convinced themselves that it's worthwhile, which
> means they have to be acknowledging that they will contribute
> significantly in the future.  All of which adds up to not many people
> taking the trouble to improve the documentation.
> 
Probably it should simply be made better-known that patches to the 
documentation don't have to be in the correct source form (docutils 
aren't used, by the way, it's a LaTeX-based system). I've seen 
statements by both Fred Drake and Skip Montanaro that they would be 
happy to accept text and put it in the right format.

Every page of the docs links to "About this document", which contains 
the following: """If you are able to provide suggested text, either to 
replace existing incorrect or unclear material, or additional text to 
supplement what's already available, we'd appreciate the contribution. 
There's no need to worry about text markup; our documentation team will 
gladly take care of that."""

So the learning curve needn't bother the casual contributor, but I 
suspect that few such potential contributors know about this.

> For those who do, of course, the current implementation is fine.
> But if the argument is that more community involvement is needed,
> then maybe the system needs to be more efficient at capturing
> that effort, by lowering the barriers to contribution.
> 
> Perhaps this just reduces to "there ought to be a wiki"?
> 
Well, perhaps the Wiki at http://wiki.python.org/moin/ should also be 
better-publicized, then?

I agree that maintaining documentation is a generic problem of the open 
source world, but it's a sad fact of life that generally people are 
better-motivated to complain about documentation (and almost everything 
else) than to help improve it.

Given that often people appear on this list for the first time without 
having used Google or the docs to try and find an answer to their 
questions, these complaints are likely to continue indefinitely ...

regards
  Steve
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC             http://www.holdenweb.com/