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.

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:

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:

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 (the problems of TeX/LaTeX))

Principles of Good Tech Writing

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

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 ①, the wiki will never be prominent. Without ②, it will remain a geek drivel.

Addendum

This essay was written in 2005. A number of things have improved, but most problems remain.

blog comments powered by Disqus