-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Sep 28, 2006, at 8:49 PM, <[EMAIL PROTECTED]> 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----- _______________________________________________ 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
