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 _______________________________________________ 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