[Python-Dev] Python Doc problems

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sep 28, 2006, at 8:49 PM, <stephen at xemacs.org> wrote:

> What is lost according to him is information about how the elements of
> a module work together.  The docstrings tend to be narrowly focused on
> the particular function or variable, and too often discuss
> implementation details.  On the other hand, manuals tend to become
> either tutorials or compedia of the docstrings.

There's no doubt that writing good documentation is an art form.   
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.   
It's not easy at all, and some of Python's documentation does better  
at this than others.  In the vast array of FOSS and for-pay docs I've  
read in my career, Python actually ain't too bad. :)

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iQCVAwUBRRx+AXEjvBPtnXfVAQJgNgP8D9f2ZUqIDTUmQU8BRx4iqjbXQANrdHt1
usZCwguIS4pa0pmUp73E514y+tDs1UzU1E2I2itIifqtKXZuPOSZYG/DWcg4h8vh
KPCygqSDNiW5dr77UP4QBXk3DOoj68E/WpLWOquoLB/eOYWOa08lh+XEJ9ShHF1F
WfHMygrtpqk=
=vEEN
-----END PGP SIGNATURE-----