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