OpenSource documentation problems

[Xah Lee]

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