[Python-Dev] Python Doc problems

[stephen at xemacs.org]

Josiah Carlson writes:

 > fine).  While I have heard comments along the lines of "the docs could
 > be better", I've never heard the claim that the Python docs are "lousy".

FYI, I have heard this, recently, from Tom Lord (aka developer of
Arch, rx, guile, etc).  Since he also took a swipe at Emacsen, I
pressed him on what he meant.  He immediately backtracked on "(all)
Python docs" and "lousy", but did say that in his opinion scripting
languages that provide docstrings have lost a fair amount of coherence
in their documentation, and that Python's are consistent with the
general trend.  (He's started using Python relatively recently and
does not claim a historical perspective.)

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.

 > If there are "rampant criticisms" of the Python docs, then those that
 > are complaining should take specific examples of their complaints to the
 > sourceforge bug tracker and submit documentation patches for the
 > relevant sections.

What they *should* do, but don't, is not necessarily a reflection on
the accuracy of what they say.

FWIW ... I find the documentation for the language, the standard
library, and the Python applications I use quite adequate for my own
use.