Perl's documentation come of age

[adDoc's networker Phil]

co.adds/doc`qc/xahlee.org:
[
. this is an editing and a commentary of the thread,
and some of the works referenced by this thread .

From: Xah Lee <xah at xahlee.org>
To: python-list at python.org
Date: 21 Sep 2005 03:41:24 -0700
Subject: Perl's documentation come[s] of age


Python [exponents] could really learn [something from
perl`s doc's:
[@] http://perldoc.perl.org/]

(*) ample code examples .

(*) code examples are linked to the appropriate doc location
for each code word in the example.

(*) written in either a task-oriented style,
[ not the jargon of abstractions and models ]
or a manifest-functionality style.
That is,
it does not [clutter the doc's expression with academic jargon or religion
about being clean, etc]
. it's either oriented towards tasks that programmers need to do,
as in module documentation,
or it's documenting the language as it manifestly functions
. (e.g. input, output, side effects; concrete description of object's
methods and variables.)
[
Think like functional programing:
input and output specification,
and document them
. This will help focus and precision in the doc
. Avoid prose-like descriptions
. Avoid drilling on remotely related tech/unix/C esoterica
. e.g. Do not mention as a documentation [item] how they are implemented
. Mention implementation [only] on the side if necessary
. This way,
the language becomes focused as a independent tool (e.g. Mathematica, Java,
Scheme, emacs)
(which may provide ample capabilities to interface/connect to other
technologies)
instead of being heavily intermixed and dependent on many other things
(unix things: Perl, Apache, shells)

]
-- The Python documentation [@]docs.python.org
is incomprehensible:
they go the extra mile to avoid any task-oriented writing or examples
as if those are pests that can lower their [snobby] status

[  example for the masses: Python Doc for gzip
Xah Lee, 2005.08.31

. today i need to use Python to compress/decompress gzip files
. Since i've read the official Python tutorial 8 months ago,
have spent 1 hour with Python every other day since,
have 14 years of computing experience,
8 years in mathematical computing,
 and 4 years in unix admin and perl,
I have quickly found the official doc:
http://python.org/doc/2.4.1/lib/module-gzip.html

I'd imagine it being a function something like:

fileContent = GzipFile(filePath, comprress/decompress)

However, scanning the doc after 20 seconds
there's no single example showing how it is used.
Instead,
the doc starts with some arcane info about compatibility with some other
compression module and other software
. Then it talks in a very haphazard way, with confused writing,
 about the main function GzipFile
. No perspectives whatsoever
about using it to solve a problem
nor a concrete description of how to use it
. Instead,
jargons about Class, Constructor, Object [ad nauseum]
are thrown together presuming the reader's expertise
with python` IO programming and gzip compression arcana.

After not understanding, and not being a Python expert,
I wanted to read about file objects but there's no link.

After locating the file object's doc page:
http://python.org/doc/2.4.1/lib/bltin-file-objects.html,
but it too is written and organized in a very unhelpful way. ]

--------------

The Perl documentation`s
presentation (organization, focus)
and technology (DHTML...)
have come of age.
However, the Perl doc`s content and writing per se, remains [very annoying]
 (and Python's is in the same ball park)

 The negative aspects people want to avoid are:

tech geek'ing
. Both perl'ers and python'ers do tech geek'ing
. That is,
mentioning of extraneous jargons, warnings, implementation details,
little style guides here and there,
unconscious opportunistic OpenSource propaganda
pitch-ins, historic information provisions, insider jokes,
and author [self-praise] on language design and comparisons...
[ie, the authors wrote large chunks of the official documentation
for no other reason than pleasing themselves;
for 99% of readers, it is incomprehensible and irrelevant.

[comment:
. actually, the fact that it was incomprehensible often [/]makes it
relevant:
for instance,
Xah Lee found that the following passage was the  "(epitome) of
[self-praise]:
"(
. lacking universally accepted terminology to talk about classes,
I will make occasional use of Smalltalk and C++ terms
    ( I would use Modula-3 terms,
      since its object-oriented semantics are closer to those of Python than
C++;
      but I expect that few readers have heard of it. )
)-epitome of propagandizing

. if you didn't know the difference between c++ and modula-3
you should be curious after knowing that now!;
and,
if you  [/]did  happen to know how much better one is than the
immensely-more popular other,
then you also know that such "(propaganda) was the equivalent of
a political activist lamenting:
"(
. I would talk to you about a world of concensus and great documentation;
but, I know you lemmings are falling hard for democracy, and over-population
!
)-epitome of good neighbor

. granted,
the passages that Xah Lee would like to have removed from the official
documentation
do sound more like a designer`s margin notes
than something from a product release;
however,
we're not just building virtual machines,
right now, we are also
trying to build [/]community .
]-comment



compulsivity

. we are not thinking clearly before writing

[comment:
. as preached by [/][extreme programming],
always assume your first attempt is a throw-away
. do not turn in the 1st draft as documentation;
turn it in as "(1st draft) or (some version < 1.0)
and use the 1st draft to understand how to concisely do the re-write .
]-comment

. toss perl`s [chatty style],
as well as Python`s [assuming that the audience is highly technical]
. Both approaches are incomprehensible.


[ ratfm: read [/]all the fine documents

. both the python and perl camps
should read the documentation of the other
-- and then,
 [/]test for clarity of thinking:

. after reading the doc's of your competition,
compare them both
to what literary critic"Xah Lee has found to be well-written
-- such as Java or Mathematica .


general education: critical thinking and doc writing abilities

. what both camps need to do is
[hone, sharpen] their skills outside of coding:
study philosophy
-- study economics, history, social sciences, and mathematics .
. Also,
study functional programming
or hang out with the functional programing community
or the hardcore GNU community .



responses to Xah Lee`s scathing rebuke


From: Steve Holden <steve at holdenweb.com>
Date: Sep 21, 2005 3:35 AM

. I offered $100 for a rewrite of the "re" [regular expressions]
documentation
[ . the test of successful task completion would be to ]
persuade 5 regular readers of c.l.py [newsgroup"comp.lang.python]
to tell me [that the rewrite] was superior
. Emails received: 0

Holden Web LLC        PyCon TX 2006
www.holdenweb.com        www.pycon.org



From: Michael Ekstrand <mekstran at iastate.edu>
Date: Sep 21, 2005 5:21 AM

. in my early stages of Python from C++,
I really didn't have any trouble figuring out what was going on.

. Python, IMHO,
 has some of the best docs in the open-source world
(on a par with Vim). [Vi IMproved -- with python scripting capability! ]
 [@] http://vimdoc.sourceforge.net/htmldoc/vimfaq.html#1.1



[editor:
. my editing of  Xah lee[@]  http://xahlee.org/
continues here:
]-editor


More about documentation can be found here:
http://www.xahlee.org/UnixResource_dir/writ/gubni_papri.html
--> Why OpenSource Documentation is of Low Quality
--> How to Write a (computer language) Tutorial
--> Notes on rewriting the Python documentation
--> On Python's Documentation
--> the TeX Pestilence
--> Python Doc Problem Example: gzip

. previously i've made serious criticisms
on
Python's documentations problems
[@] http://xahlee.org/perl-python/re-write_notes.html
[ -- though there is a python example
of an excellent [quick reference sheet] [@] http://rgruet.free.fr
-- provided by Richard Gruet ]

I have indicated that an exemplary document is
Wolfram Research Incorporated's Mathematica language
[@] http://documents.wolfram.com/mathematica/

Since Mathematica is a proprietary language
costing over a thousand dollars and most people in the IT industry are not
familiar with it,
I'd like to announce a new discovery:
the documentation of Microsoft's JavaScript
[@]
http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp

This entire document is a paragon of technical writing
. It has clarity, conciseness, and precision
. It does not abuse jargons,
it doesn't ramble,
it doesn't exhibit author masturbation,
and [it`s coverage] is complete
. The documentation set are very well organized into 3 sections:
Fundamentals, Advanced, Reference
. The tutorial section "(fundamentals) is extremely simple,
 and to the point
. The "(advanced) section gives a very concise, yet easy read
on some fine details of the language
. And its language reference section is complete and exact.

This is not the only good documentation in the industry
. In fact,
[even] the official Java documentation
(so-called Java API by Sun Microsystems) [@]
http://java.sun.com/j2se/1.4.2/docs/api/index.html
 is also extremely well-written,
[despite] the language [itself] being unnecessarily complex and [ cluttered
with technical detail,
rather than being clean, like python aspires to
. ironically, this same lack of cleanliness
provides the java doc's with the chance to
show us the proper use of technical jargon
-- an aspiration that python fails to appreciate ] .

. the fundamental reason that the documentation of
Perl, Python, Unix, Apache [and OpenSource projects in general,
    [footnote:
        except for the ones organized by
        the highly educated, eg, GNU [@] http://www.gnupress.org/
    ]-footnote
are extremely bad in multiple aspects
is a [/]degree of fanaticism that is simply UNABLE to discern quality

. This situation can be seen in the responses
to criticism of their doc's:
the OpenSource's mantra of "(contribution)
[really means]
 holding hostility against any negative criticism
unless the critic "(contributed) without charge.

[reference:
If you spend more than 30 minutes on this site, [@] xahlee.org
 please send $1 to me [@] http://paypal.com/
( pay to the order of xah at xahlee.org ) --Xah Lee, 2005.08
]-reference

[comment:
. although the profit motive does tend to raise
suspicions -- and with it, hostility --
I believe the reason that xahlee.org incites hostility
has to do with abusive, inflammatory language;
and -- as has been noted --
failing to convince our audience with a better example,
rather than punishing us for
pretending to offer "(computer programming 4 everyone)
when, in fact, what we actually do is
waste his time and patience, dragging him through a hazing
to prove his loyalty and indebtedness to the python "(fraternity) .
]-comment

. another important point is that
OpenSource [contributers]  tend to attribute their lack of quality
to "(lack of resources);
but the main cause,
is a fanaticism [that attracts contributers who are
amateurs at technical writing
(that is true of atleast the projects not organized by the highly educated,
such as GNU) [@] http://www.gnupress.org/ ]

[comment:
. if one reads "(the psychology of computer programming)[@]
www.geraldmweinberg.com/Bookstuff/Each_Book/Psychology.html
it becomes apparent that
 it is the nature of mankind -- not opensource contributers --
to disdain documentation,
and push the boring work onto
the social classes that are still struggling for fair treatment
. what is happening here is
exacly what
[/][extreme programming] preaches:

it's [/]ok to
not worry about good documentation;
[/][ because,
 you . are . not . working . on . the . [*]actual product! ]

. what [/]you are doing
is the usa`marine`s work
of exploring your problem`s solution space

. once you've figured out how to control the place,
[/]then !!!
you send in the usa`army
whose job it is to
[/][write the documentation -- [*]before writing any code --
and then tell your coders to use [*]that document -- not a morass of
contributions --
as their blueprint !!! ]

--. believe it or not,
this is actually how the "(morons)
in
every . other . field . of . engineering . do it !
a cycle of:
"(
. problem ... prototype ... architect ... mass production ... problem .
)

--. hey! we are the marines!!
all we need is a few good contributors right now .

]-comment

. I hope this accurately reflected what Xah Lee would have said
if he had to explain his concerns to his parents or his children

. it is the mission of my hobby to someday help people with just such
concerns as Xah Lee`s,
--
American Dream Documents
http://www.geocities.com/amerdreamdocs/home/
"(real opportunity starts with real documentation)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20051203/3f30814a/attachment.html>