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. -- http://mail.python.org/mailman/listinfo/python-list