On 29-sep-2006, at 4:24, Greg Ewing wrote:
An example of a good way to do it is the original Inside Macintosh series. Each chapter started with a narrative-style "About this module" kind of section, that introduced the relevant concepts and explained how they fitted together, without going into low-level details. Then there was a "Reference" section that systematically went through and gave all the details of the API.
Yep, this is exactly what I often miss in the Python library docs. The module intro sections often do contain the "executive summary" of the module, so that you can quickly see whether this module could indeed help you solve the problem at hand. But then you go straight to descriptions of classes and methods, and there is often no info on how things are plumbed together, both within the module (how the classes relate to each other) and more globally (how this module relates to others, see also). A similar thing occurs one level higher in the library hierarchy: the section introductions are little more that a list of all the modules in the section. -- Jack Jansen, <[EMAIL PROTECTED]>, http://www.cwi.nl/~jackIf I can't dance I don't want to be part of your revolution -- Emma Goldman
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
