Re: OpenSource documentation problems

Discussion in 'C Programming' started by Xah Lee, Sep 1, 2005.

  1. Xah Lee

    Xah Lee Guest

    On Python's Documentation

    Xah Lee, 20050831

    I'm very sorry to say, that the Python doc is one of the worst possible
    in the industry. I'm very sick of Perl and its intentional obfuscation
    and juvenile drivel style of its docs. I always wanted to learn Python
    as a replacement of Perl, and this year i did. I thought Python is much
    better. But now i know, that although the language is better, but its
    documentation is effectively worse than Perl's.

    • Official Perl doc: http://www.perl.com/pub/v/documentation
    • Official Python doc: http://python.org/doc/2.4.1/


    The Perl docs, although lousy in the outset because its people immerse
    in drivel. It is part of their unix culture. Nevertheless, one thing
    Perl doc is not, is that it in particular do not presume a superficial
    Computer Science stance. In fact, its culture sneer computer science
    establishment. (which caused major harm in the industry) There are
    quite a lot things wrong with Perl docs. But at least it is not shy to
    use examples, lots of them.

    Now, i have thought that Python doc is entirely different. The Python
    community in many ways are antithesis of Perl community. Python doesn't
    start with a hacking mentality, and i presume its people care a lot
    more about correctness and quality. Unfortunately, as i now know, its
    doc is even worse than Perl's. Several problems lie at the core:

      its technical writing is extremely poor. (likewise Perl)

      its technical content clearly shows that the writers can't or
    didn't think clearly. (one confused ball; likewise Perl)

      its organization exhibits the worst abstruse insensibilities of
    tech geekers. (likewise Perl, exemplified by the infamous unix man
    pages, but at least Perl/unix has spunk)

      its organization and content presentation has a computer science
    pretension.

    The Computer Science Pretension aspect is the most egregious that does
    the most damage to the Python doc. The text became incomprehensible
    abstraction sans any example, and impossible to locate desired
    functionalities. Much like unix man pages, it requires the reader to
    have familiarity with the entire doc to be able to use it fruitfully.

    As i have expressed before (see
    http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html ), the
    python doc has huge number of problems. To remedy them, it needs major
    overhaul if not complete rewrite.

    Just about the only worthwhile part of the official doc set is the
    Tutorial section.

    The “Language Reference†section (subtitled “for language
    lawyersâ€) needs to be replaced by human-readible descriptions of
    Python's functions. For exapmle, in the style of official Java doc
    (http://java.sun.com/j2se/1.4.2/docs/api/index.html). The Library
    Reference section and The Global Module Index are all in a very not
    useful state. These 3 section are all a incomprehensible blurr.

    i haven't read much of the other sections:

    • Macintosh Library Modules
    (for language lawyers)
    • Extending and Embedding
    (tutorial for C/C++ programmers)
    • Python/C API
    (reference for C/C++ programmers)
    • Documenting Python
    (information for documentation authors)
    • Installing Python Modules
    (information for installers & sys-admins)
    • Distributing Python Modules


    but all these should probably not be bundled with the official doc set.

    I would like to see the Python doc gets a complete rewrite.

    First of all, the doc system LaTeX needs to go. (TeX itself is a
    OpenSource crime, and its use as Python's doc system is a illustration
    of damage. See this unedited rant
    http://xahlee.org/Periodic_dosage_dir/t2/TeX_pestilence.html )

    Then, the doc needs to be written with a few principles.

      to communicate to programers how to use it. (as opposed to being a
    semi description of implementation and compiler process, or inline with
    some computer sciency model or software engineering metholodogy fad)

      write with the goal of effective communication. In writing, avoid
    highbrow words, long sentences, and do focus on concision and
    precision. In content, avoid philosophical outlook, jargon population,
    author masturbation, arcane technicalities, gratuitous cautions, geek
    tips, juvenile coolness ... etc.)

      document with consideration of programer's tasks to be performed.

      document orient with the language's exhibited functionalities,
    concrete behaviors. (as opposed to in some milieu of computer sciency
    model.)

      give ample examples.

    (for detail, study several of my Python criticisms from the link
    mentioned above)

    I have not been in the Python community long and have not delved into
    it. Is there other documentation that can be a basis of a new Python
    doc? The one i know is the Quick Reference by Richard Gruet. (
    http://rgruet.free.fr/PQR24/PQR2.4.html ) As a quick reference, it
    provides a concrete documentation of Python functionalities, and is a
    excellent basis for new documentation. However, being a Quick Reference
    it is very terse, consequently needs a lot work if it is to be a full
    documentation.

    Of course, the other major hurdle in progress (for a new doc) is a
    political one. It is, alas, always the biggest problem.

    the Python doc wiki at http://pydoc.amk.ca/frame.html is a great idea.
    For this to work, there are two things needs to be done:

    1. for the official python site Python.org to point to the wiki as THE
    official python doc.

    2. given a authoritarian guide in the wiki on how to write the doc.
    (the guide based on the principles i gave above. Of course, it needs to
    be clarified and elaborated with many cases in point.)

    Both are equally important. Without (1), the wiki will never be
    prominent. Without (2), it will remain a geek drivel. (in this respect,
    similar to how wikipedia's texts drift into a form of academic
    esoterica whose educational value and readibility are greatly reduced
    to the general public.)
    ---------
    This post is archived at
    http://xahlee.org/UnixResource_dir/writ/python_doc.html

    Xah

    ∑ http://xahlee.org/
    Xah Lee, Sep 1, 2005
    #1
    1. Advertising

  2. "Xah Lee" <> writes:


    > I'm very sorry to say, that the Python doc is one of the worst possible
    > in the industry. [...]


    I suppose you are going to volounteer to fix it, then. Right?

    Asbjørn
    --
    Asbjørn Sæbø, post.doc.
    Centre for Quantifiable Quality of Service in Communication Systems
    Norwegian University of Science and Technology
    <URL: http://www.q2s.ntnu.no/ >
    =?iso-8859-1?q?Asbj=F8rn_S=E6b=F8?=, Sep 1, 2005
    #2
    1. Advertising

  3. Xah Lee

    Rich Teer Guest

    On Thu, 1 Sep 2005, Asbjørn Sæbø wrote:

    > I suppose you are going to volounteer to fix it, then. Right?


    I wish he'd just volunteer to shut up--permanently.

    --
    Rich Teer, SCNA, SCSA, OpenSolaris CAB member

    President,
    Rite Online Inc.

    Voice: +1 (250) 979-1638
    URL: http://www.rite-group.com/rich
    Rich Teer, Sep 1, 2005
    #3
  4. Xah Lee

    Alan Balmer Guest

    On 1 Sep 2005 03:51:55 -0700, "Xah Lee" <> wrote:

    >On Python's Documentation


    Thinking about it, I can't imagine why I've waited so long to filter
    this idiot.
    --
    Al Balmer
    Balmer Consulting
    Alan Balmer, Sep 1, 2005
    #4
  5. Xah Lee

    Mike Meyer Guest

    Asbjørn Sæbø <> writes:
    > "Xah Lee" <> writes:
    >> I'm very sorry to say, that the Python doc is one of the worst possible
    >> in the industry. [...]

    > I suppose you are going to volounteer to fix it, then. Right?


    He once did, for one part of it. The problem he ran into was that he
    was the only person who thought his version was an improvement.

    He knows what constitutes good writing - or at least he knows how to
    quote rules that produce good writing. Unfortunately, he doesn't seem
    to be able to follow them. On top of it, his writings are typically
    strewn with errors. He really needs to find somebody proof-read his
    documents.

    <mike
    --
    Mike Meyer <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
    Mike Meyer, Sep 2, 2005
    #5
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Xah Lee
    Replies:
    4
    Views:
    354
    Mike Meyer
    Sep 2, 2005
  2. Cameron Laird
    Replies:
    1
    Views:
    641
    Josiah Carlson
    Apr 3, 2004
  3. Kenneth McDonald
    Replies:
    2
    Views:
    718
  4. Adriaan Renting

    Re: OpenSource documentation problems

    Adriaan Renting, Aug 29, 2005, in forum: Python
    Replies:
    75
    Views:
    1,210
    Mike Meyer
    Sep 10, 2005
  5. cracker
    Replies:
    2
    Views:
    380
    Sybren Stuvel
    May 19, 2006
Loading...

Share This Page