Perl's documentation has come of age:
http://perldoc.perl.org/
Python morons really need to learn:
• ample example codes.
• example codes are linked to the appropriate doc location for each
code word in the example.
• written in a task-oriented style, or manifest-functionality style.
That is, it does not have fucking pretensions of a computer science
mode or fucking clean aloofness. 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 (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 fucking status. And when the Python docs tries to document its
functions, it doesn't talk straight but instead throwing fucking bunch
of abstract objects and models jargons.
--------------
The Perl documentations, at least in its presentation (organization,
focus) and technology (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, of
its people's computer sciency aloofness and cleanness pretensions
meanwhile don't really exhibit any ability to think and write better,
are one fucking assholes.)
• 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, and Pythoner's in the fashion of
computer sciency confoundedness. 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 **** 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 or
Mathematica. (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 many
also improve vastly your critical thinking and doc writing abilities.
------------
More about documentation can be found here:
http://www.xahlee.org/UnixResource_dir/writ/gubni_papri.html
Xah
(e-mail address removed)
∑
http://xahlee.org/
.