OpenSource documentation problems

[Michael Sparks]

Bryan Olson wrote:

> A plausible theory. I have some possibly-illustrative examples
> of what I ran into within the last few weeks.

<hypothetical> Did you take what you learnt, and use that to create better
documentation to be posted on python's SF project as a patch?
</hypothetical> 

(Not aimed at you, just a preface, and you also provided the right "starter
point" to my main comment :)

> Whatever else one says about open-source documentation, keeping
> it current is a major unsolved problem.

I agree. However, the reason for this is very simple: most people who write
open source software (especially so AFAICT with python) do so on their own
time. In my experience its very difficult to get professional programmers
when they're being paid to write good documentation, and this is /despite/
the possible alternatives.

Add in the fact that part of the problem is that ability to write good code
doesn't always equate to the ability to write good documentation. Also add
in that the desire to write code isn't always accompanied by the desire to
write documentation.

Taking all that into account if it's difficult to get people who are paid
to do these things to write decent documentation (which is why people
hire tech writers), I find it suprising that people expect open source
developers to spend their own time producing high quality documentation,
which may in fact be a skill some of them lack.

Ironically though I do think the problem of documentation has been
half solved in the open source world, and it really boils down (IMO)
to companies like O'Reilly who appear to try and target popular
not-best-documented open source projects and provide the
motivation that results in good documentation.

As things go, python is pretty well documented IMO. Sure there's weak
areas, but considering this is all stuff people have done largely on their
own time, and anyone who's written docs knows it's not fun. The best way to
repay those who have spent the time writing what can be viewed as a first
draft is to provide corrections. If you (generic, not just you personally)
don't have the time, effort, inclination or effort to summarise and
feedback a documentation patch *why should anyone else* ?

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.

(Again, not specifically aimed at you, but unless you've actually
contributed back the results of your findings, you have to realise that any
reasons or excuses that apply to you may also apply to anyone/everyone in
the group and it's therefore suprising we have any docs ! :-)

Best Regards,


Michael.