[Python-Dev] Python Doc problems
barry at python.org
Fri Sep 29 03:59:24 CEST 2006
-----BEGIN PGP SIGNED MESSAGE-----
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. :)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)
-----END PGP SIGNATURE-----
More information about the Python-Dev