Documentation suggestions

[Colin J. Williams]

Michael Spencer wrote:
> 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
> 
I like the approach but more would be helpful for a current Python, 
especially with respect to types/classes.  The book is based on Python 2.1.

Colin W.