mahs at telcopartners.com
Tue Dec 6 19:29:33 CET 2005
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
> There's another struggle within the LibRef: is it a reference or a
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
(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.
More information about the Python-list