Documentation suggestions

[skip at pobox.com]

    amk> The library reference has so many modules that the table of
    amk> contents is very large.  Again, not really a problem that we can
    amk> fix; splitting it up into separate manuals doesn't seem like it
    amk> would help.

I've been meaning to tackle this with a wiki macro.  It would remember the
most frequently requested modules (say, the 10-20 most requested) and
display them in a separate alphabetical section ahead of the normal massive
module index.  That would then become the module index I bookmark.  I just
haven't had the time to implement it.

    amk> I suspect the Achilles' heel of the docs is the Language Reference.
    amk> Put aside the fact that it's not up to date with new-style classes
    amk> and other stuff; that would be fixable with some effort.

On a day-to-day basis I don't use the Language Reference at all.  Once every
couple months perhaps.  I think most people who have absorbed the basic
syntax and semantics of the language will be in the same boat.  It's the
Library Reference that requires the most effort I think.

    amk> To some degree, the guide is trying to be very formal; it's written
    amk> like a specification for an implementor, not a document that people
    amk> would read through.  But there's no other way for people to learn
    amk> about all the special object methods like __add__; the tutorial
    amk> can't cover them all, and the LibRef doesn't describe them.  So the
    amk> newbie is stuck.

I think if the newbie has outgrown the Tutorial, they should be able to
approach various bits of the Language Reference.  Perhaps some bits of its
subject matter should be tutorialized and added to the Tutorial

    amk> I don't know exactly what Bray meant, but suspect that a more
    amk> readable reference guide would have helped him understand what was
    amk> going on.

I think it would be difficult to produce a more readable reference manual
that doesn't introduce some vagueness that will be more difficult for
implementers.  The Global Index has this to say about various docs:

    Which Manual                Target Audience
    ------------                ---------------
    Library Reference           keep this under your pillow
    Language Reference          for language lawyers
    Extending and Embedding     tutorial for C/C++ programmers
    Python/C API                reference for C/C++ programmers

I think those comments are about right.

    amk> One problem with such a friendly document: it might make the Ref
    amk> Guide even more irrelevant, if we always updated the friendly
    amk> document (which is easy) and left the RefGuide to drift even
    amk> further out of date (because it's hard to update).

Somehow I think Guido would eventually put his (16-ton) foot down. ;-)

    amk> Dumping the RefGuide means there isn't a more formal-style
    amk> description of Python's semantics.  I don't know if this matters.
    amk> In theory, the implementors of Jython or IronPython could be using
    amk> the RefGuide to know what they need to implement, but in practice I
    amk> suspect implementors use the test suite and existing library as
    amk> checks.  Maybe we don't really need a tediously precise description
    amk> of Python.

I think you need something precise, if for no other reason than to
distinguish the language definition from the canonical CPython
implementation (or in the future to arbitrate disagreements betwee CPython,
PyPy, IronPython or some other newcomer).

Maybe we have the cart before the horse w.r.t. documenting changes to the
language.  When a new feature goes into the language proper it is generally
discussed on python-dev and written up in a PEP then approved by Guido.
We've generally accepted the PEP as informal documentation, but PEP's aren't
really part of the formal documentation set.  Perhaps all we need to do is
be more stringent in requiring Language Reference updates before PEP
acceptance.

Skip