Documentation suggestions

[Terry Hancock]

On Tue, 6 Dec 2005 11:31:21 -0500
"A.M. Kuchling" <amk at amk.ca> wrote:
> Here are some thoughts on reorganizing Python's
> documentation, with one big suggestion.

> There's another struggle within the LibRef: is it a
> reference or a tutorial?  

REFERENCE!  :-)

> Does it list methods in
> alphabetical order so you can look them up, or does it
> list them in a pedagogically useful order?

But, I like the *subject* categorization of modules. I would
be disappointed by a flat listing of modules (i.e. only
having the module index). IOW, I'm happy with the current
organizational outline (more or less, I'm sure I would make
small changes if I thought about it long enough).

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

I would propose adding an alternate top-level page that has
only the major headings, like this:

# Front Matter
# Contents
# 1. Introduction
# 2. Built-In Objects
# 3. Python Runtime Services
# 4. String Services
  ...
# 22. MS Windows Specific Services
# A. Undocumented Modules
# B. Reporting Bugs
# C. History and License
# Module Index
# Index
# About this document ... 

I would imagine this could be automatically generated pretty
easily from what already exists.

My reasoning is that each of the sections has grown due to
the addition of new modules, so that the large-scale
structure is getting hard to see by just looking at the
existing index page (which lists sub-headings under each of
the above).

A possible alternative would be to leave section 2
(built-ins) expanded, as that section is disproportionately
useful.

Using this index page would require you to drill down two
layers to get to individual module documentation (which is
less convenient for frequent users), but it would give a
better synoptic view at the top level (which is desireable
for people new to Python's standard library), making the
structure of the library documentation easier to figure out.

It would also reduce the feeling of information overload
that the new user experiences when encountering that page,
which would reduce "throwing up hands in disgust" and
turning to the mailing list to ask questions that ought to
be RTFM class.

I would prefer this synoptic page to be the default index
page, particularly for the benefit of newbies. But of
course, there's no reason why the existing index couldn't
exist alongside it (needs an extra link in the navbar).

The intermediate pages that the top index would link to
are already in the Python Library Reference, so the only
change is the creation of a top level page with less
information on it.

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

> Perhaps we need a friendlier counterpart to the RefGuide,
> something like the 20-page introduction to Python at the
> beginning of Beazley's  Essential Reference:
> 
> 	  * go over the statements one-by-one
> 	  * go over the basic types and their methods
> 	  * go over object semantics
> 	  * cover some of the lexical material in chapter 2
> 	  of the RefGuide * overarching principles: go into
> 	  a fair bit of detail, but
> 	    not every corner case; make the text readable,
> 	    not meticulously  precise.

That sounds like a fairly good idea.

Priorities:

  "Magic methods"
   data model: objects, classes, types, methods, etc.

> One problem with such a friendly document: it might make
> the Ref Guide even more irrelevant, if we always updated
> the friendly document (which is easy) and left the
> RefGuide to drift even further out of date (because it's
> hard to update).  I don't know if this is an argument for
> not having a friendly guide, or for dumping the RefGuide
> entirely.

Well, who needs the Reference Guide? (not a rhetorical
question).  Maybe it should be optimized for those users.

> Dumping the RefGuide means there isn't a more formal-style
> description of Python's semantics.

I'm not a language implementor, so my vote shouldn't
count that much on that point. OTOH, I *would* be a user of
the "friendlier" Language Reference, so I'm in favor of
that.

Cheers,
Terry

-- 
Terry Hancock (hancock at AnansiSpaceworks.com)
Anansi Spaceworks http://www.AnansiSpaceworks.com