perldoc Coming of Age, What Python Can Learn From?

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

Python people really need to learn these merits:

• 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 their documentations of modules, or, they document the language as it manifestly functions. (For example, input, output, side effects; concrete descriptions of object's methods and variables.)

The Python docs Overview — Python v2.7.6 documentation , is organized in some incomprehensible computer sciency structure that is impossible to find anything. And the entire doc go to the extra mile to shun any task-oriented point of view nor providing 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 douse in lingoes and abstractions.

The Perl documentations, at least in its presentation (organization, orientation) and technology format (DHTML with cross-links, syntax highlight, and bookmark features etc.) 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 doc writers should avoid are:

• Do not tech geek. Both Perlers and Pythoners do tech geeking. That is, mentioning of extraneous jargons, warnings, implementation details, providing little style guide here and there, unconscious opportunistic Open Source propaganda pitchings, historical information provisions, insider jokes, author masturbation on language design and comparisons … etc. (with Perl, this may be understandable or irrelevant because it is the Perl community's nature and design to be puerile and sloppy. They revel in it. But with Python, tech-geeking makes a fool of Pythoners because their computer sciency aloofness and cleanness pretensions while their doc don't exhibit any ability to think and write.)

• Do think clearly before writing. Both Perl and Python docs's writing qualities 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 unfit structure and formality. Both are incomprehensible.

One easy way to test this observation, is for Pythoners to read Perl docs and Perlers to read Pythoner's doc.

Pythoners will find that, you really don't know what the Perlers are talking about. Same with Perlers reading Python docs. However, you will not get the same feeling on well written docs, even if the programer is new to the language. For example: [Java's doc][ http://java.sun.com/j2se/1.4.2/docs/api/index.html ] or [Mathematica's doc][ http://reference.wolfram.com/mathematica/ ] or [Microsoft's JScript doc][ http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp ], Emacs Lisp doc .

What the Perlers and 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 your critical thinking and technical writing abilities.

(Note: at the time of this writing, Python doc is at 2.4.1 and Perl is around 5.8.7)