Documentation suggestions

[Michael Spencer]

A.M. Kuchling wrote:
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.
> 

Thanks for raising this topic, and for your on-going efforts in this field.

I use the compiled html help file provided by PythonWin, which includes all the 
core documentation.  I usually use the index interface, not the table of 
contents (the main exception is the LibRef, see below).  In this form, the 
structure of the documentation is less important than how good the index is. 
Unfortunately, the "additional documentation', including, in particular, your re 
HowTo is linked, but not indexed and is therefore less accessible.

> The tutorial seems to be in pretty good shape because Raymond
...
Agreed, but as you say below, there may be friendlier forms available for the 
first-timer.

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

I want it to help answer questions of the form "What's in the the library that 
might help me do x?"  For this case, some of the current section structure is 
not that helpful.  "Miscellaneous Services", in particular, gives no clue to 
treasures it contains.  I would prefer, for example, to see the data structure 
modules: collections, heapq, array etc... given their own section. 
Documentation/testing, cmd/options might be other candidates to draw together 
currently related material more meaningfully.

   Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order?  I
> think it has to be a reference;

A reference, yes, but not necessarily alphabetical if another organization is 
more communicative.  itertools is a good example where alphabetic presentation 
makes perfect sense, since the functions are more-or-less peers; the math 
functions are usefully classified by topic; textwrap presents most commonly-used 
functions first; several modules document classes before convenience functions. 
   Each of these has its merits, and I don't see a lot of mileage in trying to 
standardize them, given how varied modules are.  However, whatever the reference 
structure, examples add significantly to the value to me.

...

> 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.
> 

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

I find very little of value to me in the Language Ref.  Special methods are the 
crucial exception.  Perhaps they, together with a description of class semantics 
(including metaclasses and descriptors) could be moved to the Built-in types 
section of the LibRef, where some related material is already.

I don't know whether the rest of the Language reference is of use to 
implementers, but given the proliferation of implementations beyond Cpython 
(Jython, IronPython, pypy) I would speculate that a formal specification is now 
more important rather than less.  However, perhaps it would be possible to 
express the specification more succinctly via tests instead of a manual.

...
> 
> 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:

I did't know this source, but I just skimmed it at 
http://www.amazon.com/gp/reader/0735709017/ref=sib_dp_pt/103-1276064-0751851#reader-page
(not sure if this is a session link), and I agree it's a very clear 
introduction.   Probably better first reading than the existing tutorial.

...


Michael