Home > Archive > Unix Programming > September 2005 > Perl's documentation come of age
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Perl's documentation come of age
|
|
| Xah Lee 2005-09-21, 7:57 am |
| Perl's documentation has come of age: http://perldoc.perl.org/
Python morons really need to learn:
=E2=80=A2 ample example codes.
=E2=80=A2 example codes are linked to the appropriate doc location for each
code word in the example.
=E2=80=A2 written in a task-oriented style, or manifest-functionality style.
That is, it does not have XXXXing pretensions of a computer science
mode or XXXXing 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 XXXXing status. And when the Python docs tries to document its
functions, it doesn't talk straight but instead throwing XXXXing 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:
=E2=80=A2 do not tech g . Both perlers and pythoners do tech ging. 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 XXXXing assholes.)
=E2=80=A2 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 XXXX 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_...ubni_papri.html
Xah
xah@xahlee.org
=E2=88=91 http://xahlee.org/
| |
| Keith Thompson 2005-09-21, 6:59 pm |
| "Xah Lee" <xah@xahlee.org> writes:
[ the usual ]
+-------------------+ .:\:\:/:/:.
| PLEASE DO NOT | :.:\:\:/:/:.:
| FEED THE TROLLS | :=.' - - '.=:
| | '=(\ 9 9 /)='
| Thank you, | ( (_) )
| Management | /`-vvv-'\
+-------------------+ / \
| | @@@ / /|,,,,,|\ \
| | @@@ /_// /^\ \\_\
@x@@x@ | | |/ WW( ( ) )WW
\||||/ | | \| __\,,\ /,,/__
\||/ | | | jgs (______Y______)
/\/\/\/\/\/\/\/\//\/\\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
========================================
======================
--
Keith Thompson (The_Other_Keith) kst-u@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.
| |
| Måns Rullgård 2005-09-21, 6:59 pm |
| This guy deserves two ascii trolls:
___________________
/| /| | |
||__|| | Please do |
/ O O\__ NOT |
/ \ feed the |
/ \ \ trolls |
/ _ \ \ ______________|
/ |\____\ \ ||
/ | | | |\____/ ||
/ \|_|_|/ \ __||
/ / \ |____| ||
/ | | /| | --|
| | |// |____ --|
* _ | |_|_|_| | \-/
*-- _--\ _ \ // |
/ _ \\ _ // | /
* / \_ /- | - | |
* ___ c_c_c_C/ \C_c_c_c____________
+-------------------+ .:\:\:/:/:.
| PLEASE DO NOT | :.:\:\:/:/:.:
| FEED THE TROLLS | :=.' - - '.=:
| | '=(\ 9 9 /)='
| Thank you, | ( (_) )
| Management | /`-vvv-'\
+-------------------+ / \
| | @@@ / /|,,,,,|\ \
| | @@@ /_// /^\ \\_\
@x@@x@ | | |/ WW( ( ) )WW
\||||/ | | \| __\,,\ /,,/__
\||/ | | | jgs (______Y______)
/\/\/\/\/\/\/\/\//\/\\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
========================================
======================
--
Måns Rullgård
mru@inprovide.com
|
|
|
|
|