Perl and Python Documentations

Xah Lee, 20050921

Perl's documentation has come of age: http://perldoc.perl.org/

Python people really need to learn:

• ample code examples.

• keywords in examples are linked to the appropriate doc location.

• written in a task-oriented style, or manifest-functionality style.
That is, it does not have pretensions of a computer sciency mode or
austerity. It either is oriented towards tasks programers need to do,
as in module documentations, or document the language as it manifestly
functions. (e.g. input, output, side effects; concrete description of
object's methods and variables.)

The Python docs (http://docs.python.org/), is organized in some
incomprehensible computer sciency structure that is impossible to find
anything. And the entire doc go to the extra mile to avoid any
task-oriented writing or examples as if those are pests that can lower
their status. And when the Python doc tries to document its functions,
it doesn't talk straight but instead throwing a bunch of abstract
objects and models jargons.

The Perl documentations, at least in its presentation (organization,
orientation) and technology format (DHTML...) aspects, has come of age.

However, the Perl doc's content and writing per se, remains the worst
garbage possible. (and Python's is in the same ball park) The negative
aspects people want to avoid are:

• Do not tech geek. Both perlers and pythoners do tech geeking. That
is, mentioning of extraneous jargons, warnings, implementation details,
little style guide here and there, unconscious opportunistic OpenSource
propaganda pitch-ins, historic information provisions, insider jokes,
author masturbation on language design and comparisons... etc. (with
Perl, this may be understandable or irrelevant because it is their
nature and design to be juvenile. They revel in it. But with Python,
it's worse because of Pythoner's computer sciency aloofness and
cleanness pretensions meanwhile don't really exhibit any ability to
think and write better.)

• Do think clearly before writing. Both Perl and Python docs's writing
quality are extremely bad. What they primarily lack is the ability to
think clearly before writing. Perl docs write in the fashion of
happy-go-lucky juvenile ramble. They write down their thought process
and intuitive understanding of how things are, and meanwhile don't
hesitate to throw in childish unix jokes and cheap word play.
Pythoner's in the fashion of computer sciency confoundedness. They
don't have mathematical clarity of how things are, but meanwhile force
their understanding into a irrelevant fomal structure with computer
science jargons. Both are incomprehensible.

One easy way to test this, is for Pythoners to read Perl docs and vice
versa.

Pythoners will find that, you really don't know what the Perlers are
talking about. Same with Perler with Python docs. However, you will not
get the same feeling on well written docs, such as Java's doc or
Mathematica's doc. (assume that the people here have been in the
programing industry for several years, and are not familiar with the
other languages in question.)

What the Perlers & Pythoners need to do, is to horn their skills
outside of coding. Study philosophy, study economics, history, social
sciences, and mathematics. Also, study functional programing or hang
out in functional programing communities or hardcore GNU community will
also improve vastly

-------------
this post is archived at:
http://xahlee.org/perl-python/perl_python_docs.html

☄