On 08/11/2009 01:47 AM, Antoine Pitrou wrote: > r<rt8396<at> gmail.com> writes: >> On Aug 9, 11:02 pm, David Lyon<david.l...@preisshare.net> wrote: >>> Since you're talking about documentation, which is a part of python, >>> don't you think you should be discussing it on python-dev ? >> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better >> idea, lets go to the IRS and see if we can persuade them to stop >> taxing us... > > You know, the most interesting thing in this thread is certainly its title : > « Social problems of Python doc » > > Yes, the little social problem here should be clear: if you have complaints to > voice or improvements to suggest to the Python docs, you should do so on the > issue tracker (*). For most topics, this is the only reasonable way to signal > problems to the Python developers community, and so it is in most free > software > / open source projects.
"the *only* reasonable way"? That's clearly wrong (unless you want to wiggle in the room provided by "reasonable" or "most"). There is discussion on the dev list, there is discussion here. The issue tracker is fine for many things, but the process it provides is equivalent to peep-hole optimization. How does one submit a tracker issue for something like the overall organization of the docs (for example, the mis-placement of things like data- types in the library manual rather than the language manual)? The big problem with the docs is poor writing (this includes not using examples when they can help explain something more clearly than verbiage alone). It is understandable why this should be so -- most programmers are good at and enjoy programming, not writing and the python community is, say, about 99.9% programmers. This is why all the attempts (at least that I've noticed) are programming focused -- build a wiki, write a new doc processing framework, etc. Unfortunately none of those addresses the real problem -- the need for clear, well written, well organized *content*. I don't see how telling people to submit tracker issues will solve this problem. I can rewrite some section so it sounds good to me, but likely it will be just as bad (perhaps in different ways) that what is there. The post that started this thread proposed something like paying professional writers to improve the docs. This may or may not be a practical suggestion. But the immediate response it engendered was an auto-immune-like group response: the docs are great already, don't complain, fix them yourself, yada, yada; the same response that any criticism of free software produces. It's really too bad the the python community can't seriously discuss ways to improves the docs. There are other possibilities for instance the Fedora Docs project (can't say I'm impressed by what they've produced but that doesn't mean their model is useless). There is a need for an approval process managed by someone who actually understands what good technical writing is. And perhaps editors who can polish or work with programmers who provide the raw technical description of some module. Some kind of higher level more global process is the only way I can see that the docs will be improved to any sort or professional standard. I don't see how issues like this will be addressed by submitting tracker items. Personally, I have given up on this issue. The social factors involved really pretty much determine that the Python docs will never reach a very high quality -- that's just the way it is and I've come to accept that. -- http://mail.python.org/mailman/listinfo/python-list
