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