By the way, i have sent my criticisms to the proper python doc maintainer or mailing list several months ago.
------------- i'm very sorry to say, that the Python doc is one of the worst possible in the industry. I'm very sick of Perl and its intentional obfuscation and juvenile drivel style of its docs. I always wanted to learn Python as a replacement of Perl, and this year i did. I thought Python is much better. But now i know, that although the language is better, but its documentation is effectively worse than Perl's. The Perl docs, although lousy in the outset because its people immerse in drivel. It is part of their unix culture. Nevertheless, one thing Perl doc is not, is that it in particular do not presume a superficial Computer Science stance. In fact, its culture sneer computer science establishment. (which i caused major harm in the industry) There are quite a lot things wrong with Perl docs. But at least it is not shy to use examples, lots of them. Now, i have thought that Python doc is entirely different. The Python community in many ways are antithesis of Perl community. Python doesn't start with a hacking mentality, and i presume it to have a community who care about correctness and quality. Unfortunately, as i now know, its doc is the worst and almost useless piece of shit. Several problems lies at the core: * its technical writing is extremely poor. * its technical content clearly shows that the writers can't or didn't think clearly. (one confused ball) * its organization exhibits the worst abstruse insensibilities of tech geekers. ------------ as i have expressed before (see http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html ), the python doc has huge number of problems. To remedy them, it needs major overhaul if not complete rewrite. Just about the only worthwhile part of the official doc set is the Tutorial section. The “Language Reference” section, Library Reference, and The Global Module Index are totally crap and need to be deleted entirely. (i haven't read much of the other sections, but i don't assume they are much better) ------------- I would like to see the Python doc gets a complete rewrite. First of all, the doc system LaTex needs to go. (TeX itself is a OpenSource crime, see this unedited rant http://xahlee.org/Periodic_dosage_dir/t2/TeX_pestilence.html ) Then, the doc needs to be written with a few principles. * to communicate to programers how to use it. (as opposed to being a compiling specification or inline with some computer sciency model) * write with the goal of effective communication. In the writing, avoid big Engish words, long sentences, and focus on precision. In content, avoid philosophical outlook, jargon population, author masturbation, arcane technicalities, gratuitous cautions, geek tips, juvenile coolness ... etc.) * document with consideration of tasks to be performed. * document orient with the language's exhibited functionalities, concrete behaviors. (as opposed to in some milieu of software engineering methodology) * give ample examples. (for detail, study several of my Python criticisms from the link mentioned above) -------------- I have not been in the Python community long and have not delved into it. Is there other documentation that can be a basis of a new python doc? The one i know is the Quick Reference by Richard Gruet. However, it is just a Quick Reference but can be a basis if we lack anything else. Also, i have happened to read the O'Reilly Python book years ago. That book is crap. I have also read parts of the Python Cookbook. Probably half of this book is also crap. Of course, the other major hurdle in progress (for a new doc) is a political one. It is, alas, always the biggest problem. ----------- the python doc wiki given at http://pydoc.amk.ca/frame.html is a great idea. For this to work, there are two things needs to be done, both are equally important: 1. for the official python site Python.org to point to the wiki as THE official python doc. 2. given a authoritarian guide in the wiki on how to write the doc. (the guide based on the principles i gave above. Of course, it needs to be clarified and elaborated with many cases in point.) Without (1), the wiki will never be prominent. Without (2), it will remain a geek drivel. (in this respect, similar to how wikipedia's texts drift into a form of academic esoterica whose educational value are greatly reduced to the general public.) -------- this post is archived at http://xahlee.org/UnixResource_dir/writ/python_doc.html Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list
