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. -- http://mail.python.org/mailman/listinfo/python-list