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, <Jack.Jansen at cwi.nl>, http://www.cwi.nl/~jack If I can't dance I don't want to be part of your revolution -- Emma Goldman -------------- next part -------------- A non-text attachment was scrubbed... Name: smime.p7s Type: application/pkcs7-signature Size: 2255 bytes Desc: not available Url : http://mail.python.org/pipermail/python-dev/attachments/20060929/7f604aa0/attachment.bin
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4