OpenSource documentation problems

[Terry Hancock]

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.

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"?

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com