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