Why Python's Documentation Sucks

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://perldoc.perl.org/
• 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 does not assume a superficial Computer Science stance. In fact, its culture sneers computer science establishment. (which caused massive damage in the IT 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 system to be able to benefit from it comfortably.

Keep Under Your Pillow??

As i have expressed before, the Python doc has a number of fundamental problems. To remedy them, it needs major overhaul.

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-readable descriptions of Python's functions. For example, 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 blur.

The following 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 and sys-admins)
• Distributing Python Modules

should probably not be bundled with the language as a downloadable set, since each are of interest to perhaps 1% of Python users.

Kick LaTeX Out of the Door

I would like to see the Python doc gets a complete rewrite.

First of all, the doc system LaTeX needs to go. (See bottom of Notes on Rewriting Python Regex Documentation and The TeX Pestilence: Why TeX/LaTeX Sucks)

Principles of Good Tech Writing

Then, the doc needs to be written with a few principles.

• To communicate to programers how to use it. (as opposed to being a description of implementation or compiler process, or inline with some computer sciency model or software engineering methodology 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 showoff, arcane technicalities, geek tips, coolness exhibition, Open Source propaganda.)
• Document with consideration of tasks to be performed.
• Document orient with the language's manifested functionalities, concrete behaviors. (as opposed to in some milieu of computer sciency mode.)
• Give ample examples.

For detail, see: Python Documentation Problems .

Quick Reference by Richard Gruet

There is a Quick Reference by Richard Gruet at 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.

O, Politics!

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:

• For the official Python site Python.org to point to the wiki as THE official Python doc.
• 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.