co.adds/doc`qc/xahlee.org:<br>
[<br>
. this is an editing and a commentary of the thread,<br>
and some of the works referenced by this thread .<br>
<br>
From: Xah Lee <<a href="mailto:xah@xahlee.org">xah@xahlee.org</a>>    <br>
To: <a href="mailto:python-list@python.org">python-list@python.org</a><br>
Date: 21 Sep 2005 03:41:24 -0700<br>
Subject: Perl's documentation come[s] of age<br>
<br>
<br>
Python [exponents] could really learn [something from <br>
perl`s doc's: <br>
[@] <a href="http://perldoc.perl.org/]">http://perldoc.perl.org/]</a><br>
<br>
(*) ample code examples .<br>
<br>
(*) code examples are linked to the appropriate doc location <br>
for each code word in the example.<br>
<br>
(*) written in either a task-oriented style, <br>
[ not the jargon of abstractions and models ]<br>
or a manifest-functionality style.<br>
That is, <br>
it does not [clutter the doc's expression with academic jargon or religion about being clean, etc]<br>
. it's either oriented towards tasks that programmers need to do, <br>
as in module documentation, <br>
or it's documenting the language as it manifestly functions<br>
. (e.g. input, output, side effects; concrete description of object's methods and variables.)<br>
[<br>
Think like functional programing: <br>
input and output specification, <br>
and document them<br>
. This will help focus and precision in the doc<br>
. Avoid prose-like descriptions<br>
. Avoid drilling on remotely related tech/unix/C esoterica<br>
. e.g. Do not mention as a documentation [item] how they are implemented<br>
. Mention implementation [only] on the side if necessary<br>
. This way, <br>
the language becomes focused as a independent tool (e.g. Mathematica, Java, Scheme, emacs) <br>
(which may provide ample capabilities to interface/connect to other technologies)<br>
instead of being heavily intermixed and dependent on many other things <br>
(unix things: Perl, Apache, shells)<br>
<br>
]<br>
-- The Python documentation [@]docs.python.org<br>
is incomprehensible:<br>
they go the extra mile to avoid any task-oriented writing or examples <br>
as if those are pests that can lower their [snobby] status<br>
<br>
[  example for the masses: Python Doc for gzip<br>
Xah Lee, 2005.08.31<br>
<br>
. today i need to use Python to compress/decompress gzip files<br>
. Since i've read the official Python tutorial 8 months ago, <br>
have spent 1 hour with Python every other day since, <br>
have 14 years of computing experience, <br>
8 years in mathematical computing,<br>
 and 4 years in unix admin and perl,<br>
I have quickly found the official doc: <br>
<a href="http://python.org/doc/2.4.1/lib/module-gzip.html">http://python.org/doc/2.4.1/lib/module-gzip.html</a><br>
<br>
I'd imagine it being a function something like:<br>
<br>
fileContent = GzipFile(filePath, comprress/decompress)<br>
<br>
However, scanning the doc after 20 seconds <br>
there's no single example showing how it is used.<br>
Instead, <br>
the doc starts with some arcane info about compatibility with some other compression module and other software<br>
. Then it talks in a very haphazard way, with confused writing,<br>
 about the main function GzipFile<br>
. No perspectives whatsoever <br>
about using it to solve a problem <br>
nor a concrete description of how to use it<br>
. Instead, <br>
jargons about Class, Constructor, Object [ad nauseum]<br>
are thrown together presuming the reader's expertise <br>
with python` IO programming and gzip compression arcana.<br>
<br>
After not understanding, and not being a Python expert,<br>
I wanted to read about file objects but there's no link.<br>
<br>
After locating the file object's doc page: <br>
<a href="http://python.org/doc/2.4.1/lib/bltin-file-objects.html">http://python.org/doc/2.4.1/lib/bltin-file-objects.html</a>, <br>
but it too is written and organized in a very unhelpful way. ]<br>
<br>
--------------<br>
<br>
The Perl documentation`s <br>
presentation (organization, focus) <br>
and technology (DHTML...)<br>
have come of age.<br>
However, the Perl doc`s content and writing per se, remains [very annoying]<br>
 (and Python's is in the same ball park)<br>
<br>
 The negative aspects people want to avoid are:<br>
<br>
tech geek'ing<br>
. Both perl'ers and python'ers do tech geek'ing<br>
. That is, <br>
mentioning of extraneous jargons, warnings, implementation details,<br>
little style guides here and there, <br>
unconscious opportunistic OpenSource propaganda <br>
pitch-ins, historic information provisions, insider jokes,<br>
and author [self-praise] on language design and comparisons... <br>
[ie, the authors wrote large chunks of the official documentation<br>
for no other reason than pleasing themselves;<br>
for 99% of readers, it is incomprehensible and irrelevant.<br>
<br>
[comment:<br>
. actually, the fact that it was incomprehensible often [/]makes it relevant:<br>
for instance,<br>
Xah Lee found that the following passage was the  "(epitome) of  [self-praise]:<br>
"(<br>
. lacking universally accepted terminology to talk about classes, <br>
I will make occasional use of Smalltalk and C++ terms<br>
    ( I would use Modula-3 terms, <br>
      since its object-oriented semantics are closer to those of Python than C++;<br>
      but I expect that few readers have heard of it. )<br>
)-epitome of propagandizing<br>
<br>
. if you didn't know the difference between c++ and modula-3<br>
you should be curious after knowing that now!;<br>
and, <br>
if you  [/]did  happen to know how much better one is than the immensely-more popular other,<br>
then you also know that such "(propaganda) was the equivalent of <br>
a political activist lamenting:<br>
"(<br>
. I would talk to you about a world of concensus and great documentation;<br>
but, I know you lemmings are falling hard for democracy, and over-population !<br>
)-epitome of good neighbor<br>
<br>
. granted,<br>
the passages that Xah Lee would like to have removed from the official documentation<br>
do sound more like a designer`s margin notes<br>
than something from a product release;<br>
however,<br>
we're not just building virtual machines,<br>
right now, we are also <br>
trying to build [/]community .<br>
]-comment<br>
<br>
<br>
<br>
compulsivity<br>
<br>
. we are not thinking clearly before writing<br>
<br>
[comment:<br>
. as preached by [/][extreme programming],<br>
always assume your first attempt is a throw-away<br>
. do not turn in the 1st draft as documentation;<br>
turn it in as "(1st draft) or (some version < 1.0)<br>
and use the 1st draft to understand how to concisely do the re-write .<br>
]-comment<br>
<br>
. toss perl`s [chatty style], <br>
as well as Python`s [assuming that the audience is highly technical]<br>
. Both approaches are incomprehensible.<br>
<br>
<br>
[ ratfm: read [/]all the fine documents<br>
<br>
. both the python and perl camps <br>
should read the documentation of the other<br>
-- and then,<br>
 [/]test for clarity of thinking:<br>
<br>
. after reading the doc's of your competition,<br>
compare them both <br>
to what literary critic"Xah Lee has found to be well-written <br>
-- such as Java or Mathematica .<br>
<br>
<br>
general education: critical thinking and doc writing abilities<br>
<br>
. what both camps need to do is <br>
[hone, sharpen] their skills outside of coding:<br>
study philosophy<br>
-- study economics, history, social sciences, and mathematics .<br>
. Also, <br>
study functional programming <br>
or hang out with the functional programing community<br>
or the hardcore GNU community . <br>
<br>
<br>
<br>
responses to Xah Lee`s scathing rebuke<br>
<br>
<br>
From: Steve Holden <<a href="mailto:steve@holdenweb.com">steve@holdenweb.com</a>>    <br>
Date: Sep 21, 2005 3:35 AM<br>
<br>
. I offered $100 for a rewrite of the "re" [regular expressions] documentation <br>
[ . the test of successful task completion would be to ]<br>
persuade 5 regular readers of <a href="http://c.l.py">c.l.py</a> [newsgroup"comp.lang.python]<br>
to tell me [that the rewrite] was superior<br>
. Emails received: 0<br>
<br>
Holden Web LLC        PyCon TX 2006<br>
<a href="http://www.holdenweb.com">www.holdenweb.com</a>        <a href="http://www.pycon.org">www.pycon.org</a><br>
<br>
<br>
<br>
From: Michael Ekstrand <<a href="mailto:mekstran@iastate.edu">mekstran@iastate.edu</a>>    <br>
Date: Sep 21, 2005 5:21 AM<br>
<br>
. in my early stages of Python from C++, <br>
I really didn't have any trouble figuring out what was going on.<br>
<br>
. Python, IMHO,<br>
 has some of the best docs in the open-source world <br>
(on a par with Vim). [Vi IMproved -- with python scripting capability! ]<br>
 [@] <a href="http://vimdoc.sourceforge.net/htmldoc/vimfaq.html#1.1">http://vimdoc.sourceforge.net/htmldoc/vimfaq.html#1.1</a><br>
<br>
<br>
<br>
[editor:<br>
. my editing of  Xah lee[@]  <a href="http://xahlee.org/">http://xahlee.org/</a><br>
continues here:<br>
]-editor<br>
<br>
<br>
More about documentation can be found here:<br>
<a href="http://www.xahlee.org/UnixResource_dir/writ/gubni_papri.html">http://www.xahlee.org/UnixResource_dir/writ/gubni_papri.html</a><br>
--> Why OpenSource Documentation is of Low Quality<br>
--> How to Write a (computer language) Tutorial<br>
--> Notes on rewriting the Python documentation<br>
--> On Python's Documentation<br>
--> the TeX Pestilence<br>
--> Python Doc Problem Example: gzip<br>
<br>
. previously i've made serious criticisms <br>
on <br>
Python's documentations problems <br>
[@] <a href="http://xahlee.org/perl-python/re-write_notes.html">http://xahlee.org/perl-python/re-write_notes.html</a><br>
[ -- though there is a python example <br>
of an excellent [quick reference sheet] [@] <a href="http://rgruet.free.fr">http://rgruet.free.fr</a><br>
-- provided by Richard Gruet ]<br>
<br>
I have indicated that an exemplary document is <br>
Wolfram Research Incorporated's Mathematica language<br>
[@] <a href="http://documents.wolfram.com/mathematica/">http://documents.wolfram.com/mathematica/</a><br>
<br>
Since Mathematica is a proprietary language <br>
costing over a thousand dollars and most people in the IT industry are not familiar with it, <br>
I'd like to announce a new discovery:<br>
the documentation of Microsoft's JavaScript<br>
[@] <a href="http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp">http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp</a><br>
<br>
This entire document is a paragon of technical writing<br>
. It has clarity, conciseness, and precision<br>
. It does not abuse jargons, <br>
it doesn't ramble, <br>
it doesn't exhibit author masturbation, <br>
and [it`s coverage] is complete<br>
. The documentation set are very well organized into 3 sections: <br>
Fundamentals, Advanced, Reference<br>
. The tutorial section "(fundamentals) is extremely simple,<br>
 and to the point<br>
. The "(advanced) section gives a very concise, yet easy read <br>
on some fine details of the language<br>
. And its language reference section is complete and exact.<br>
<br>
This is not the only good documentation in the industry<br>
. In fact, <br>
[even] the official Java documentation <br>
(so-called Java API by Sun Microsystems) [@] <a href="http://java.sun.com/j2se/1.4.2/docs/api/index.html">http://java.sun.com/j2se/1.4.2/docs/api/index.html</a><br>
 is also extremely well-written, <br>
[despite] the language [itself] being unnecessarily complex and [ cluttered with technical detail, <br>
rather than being clean, like python aspires to <br>
. ironically, this same lack of cleanliness <br>
provides the java doc's with the chance to <br>
show us the proper use of technical jargon <br>
-- an aspiration that python fails to appreciate ] .<br>
<br>
. the fundamental reason that the documentation of <br>
Perl, Python, Unix, Apache [and OpenSource projects in general,<br>
    [footnote:<br>
        except for the ones organized by <br>
        the highly educated, eg, GNU [@] <a href="http://www.gnupress.org/">http://www.gnupress.org/</a> <br>
    ]-footnote<br>
are extremely bad in multiple aspects <br>
is a [/]degree of fanaticism that is simply UNABLE to discern quality<br>
<br>
. This situation can be seen in the responses <br>
to criticism of their doc's:<br>
the OpenSource's mantra of "(contribution)<br>
[really means]<br>
 holding hostility against any negative criticism <br>
unless the critic "(contributed) without charge.<br>
<br>
[reference:<br>
If you spend more than 30 minutes on this site, [@] <a href="http://xahlee.org">xahlee.org</a> <br>
 please send $1 to me [@] <a href="http://paypal.com/">http://paypal.com/</a> <br>
( pay to the order of <a href="mailto:xah@xahlee.org">xah@xahlee.org</a> ) --Xah Lee, 2005.08<br>
]-reference<br>
<br>
[comment: <br>
. although the profit motive does tend to raise <br>
suspicions -- and with it, hostility --<br>
I believe the reason that <a href="http://xahlee.org">xahlee.org</a> incites hostility<br>
has to do with abusive, inflammatory language;<br>
and -- as has been noted --<br>
failing to convince our audience with a better example,<br>
rather than punishing us for <br>
pretending to offer "(computer programming 4 everyone)<br>
when, in fact, what we actually do is<br>
waste his time and patience, dragging him through a hazing<br>
to prove his loyalty and indebtedness to the python "(fraternity) .<br>
]-comment<br>
<br>
. another important point is that <br>
OpenSource [contributers]  tend to attribute their lack of quality<br>
to "(lack of resources);<br>
but the main cause,<br>
is a fanaticism [that attracts contributers who are <br>
amateurs at technical writing<br>
(that is true of atleast the projects not organized by the highly educated,<br>
such as GNU) [@] <a href="http://www.gnupress.org/">http://www.gnupress.org/</a> ]<br>
<br>
[comment:<br>
. if one reads "(the psychology of computer programming)[@] <a href="http://www.geraldmweinberg.com/Bookstuff/Each_Book/Psychology.html">www.geraldmweinberg.com/Bookstuff/Each_Book/Psychology.html</a><br>
it becomes apparent that<br>
 it is the nature of mankind -- not opensource contributers --<br>
to disdain documentation, <br>
and push the boring work onto <br>
the social classes that are still struggling for fair treatment<br>
. what is happening here is <br>
exacly what <br>
[/][extreme programming] preaches:<br>
<br>
it's [/]ok to <br>
not worry about good documentation;<br>
[/][ because,<br>
 you . are . not . working . on . the . [*]actual product! ]<br>
<br>
. what [/]you are doing <br>
is the usa`marine`s work <br>
of exploring your problem`s solution space<br>
<br>
. once you've figured out how to control the place,<br>
[/]then !!!<br>
you send in the usa`army<br>
whose job it is to<br>
[/][write the documentation -- [*]before writing any code --<br>
and then tell your coders to use [*]that document -- not a morass of contributions -- <br>
as their blueprint !!! ]<br>
<br>
--. believe it or not, <br>
this is actually how the "(morons) <br>
in <br>
every . other . field . of . engineering . do it !<br>
a cycle of:<br>
"(<br>
. problem ... prototype ... architect ... mass production ... problem .<br>
)<br>
<br>
--. hey! we are the marines!! <br>
all we need is a few good contributors right now .<br>
<br>
]-comment<br>
<br>
. I hope this accurately reflected what Xah Lee would have said<br>
if he had to explain his concerns to his parents or his children<br>
<br>
. it is the mission of my hobby to someday help people with just such concerns as Xah Lee`s,<br>-- <br>American Dream Documents<br><a href="http://www.geocities.com/amerdreamdocs/home/">http://www.geocities.com/amerdreamdocs/home/
</a><br>"(real opportunity starts with real documentation)