[Python-Dev] Python Doc problems

[Jack Jansen]

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