OpenSource documentation problems

[Xah Lee]

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
 xah at xahlee.org
∑ http://xahlee.org/