On Python's Documentation Xah Lee, 20050831
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. • Official Perl doc: http://www.perl.com/pub/v/documentation • Official Python doc: http://python.org/doc/2.4.1/ 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 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 its people care a lot more about correctness and quality. Unfortunately, as i now know, its doc is even worse than Perl's. Several problems lie at the core: its technical writing is extremely poor. (likewise Perl) its technical content clearly shows that the writers can't or didn't think clearly. (one confused ball; likewise Perl) its organization exhibits the worst abstruse insensibilities of tech geekers. (likewise Perl, exemplified by the infamous unix man pages, but at least Perl/unix has spunk) its organization and content presentation has a computer science pretension. The Computer Science Pretension aspect is the most egregious that does the most damage to the Python doc. The text became incomprehensible abstraction sans any example, and impossible to locate desired functionalities. Much like unix man pages, it requires the reader to have familiarity with the entire doc to be able to use it fruitfully. 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 (subtitled “for language lawyers”) needs to be replaced by human-readible descriptions of Python's functions. For exapmle, in the style of official Java doc (http://java.sun.com/j2se/1.4.2/docs/api/index.html). The Library Reference section and The Global Module Index are all in a very not useful state. These 3 section are all a incomprehensible blurr. i haven't read much of the other sections: • Macintosh Library Modules (for language lawyers) • Extending and Embedding (tutorial for C/C++ programmers) • Python/C API (reference for C/C++ programmers) • Documenting Python (information for documentation authors) • Installing Python Modules (information for installers & sys-admins) • Distributing Python Modules but all these should probably not be bundled with the official doc set. 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, and its use as Python's doc system is a illustration of damage. 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 semi description of implementation and compiler process, or inline with some computer sciency model or software engineering metholodogy fad) write with the goal of effective communication. In writing, avoid highbrow words, long sentences, and do focus on concision and precision. In content, avoid philosophical outlook, jargon population, author masturbation, arcane technicalities, gratuitous cautions, geek tips, juvenile coolness ... etc.) document with consideration of programer's tasks to be performed. document orient with the language's exhibited functionalities, concrete behaviors. (as opposed to in some milieu of computer sciency model.) 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. ( http://rgruet.free.fr/PQR24/PQR2.4.html ) As a quick reference, it provides a concrete documentation of Python functionalities, and is a excellent basis for new documentation. However, being a Quick Reference it is very terse, consequently needs a lot work if it is to be a full documentation. 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 at http://pydoc.amk.ca/frame.html is a great idea. For this to work, there are two things needs to be done: 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.) Both are equally important. 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 and readibility 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
