[Python-Dev] Python Doc problems

Greg Ewing greg.ewing at canterbury.ac.nz
Fri Sep 29 04:24:23 CEST 2006


Barry Warsaw wrote:

> There's also the pull between wanting to write reference docs for  
> those who know what they've forgotten (I love that phrase!) and  
> writing the introductory or "how it hangs together" documentation. 

The trick to this, I think, is not to try to make the same
piece of documentation serve both purposes.

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.

While Inside Mac could often be criticised for omitting
rather important info in either section now and then, I
think they had the basic structure of the docs right.

--
Greg


More information about the Python-Dev mailing list