Python Library Reference is tutorial, not reference

[Josiah Carlson]

[Snip statements regarding Python's documentation not being great]

Having used (read and written) pydoc/javadoc-style documentation before,
I am personally not a big fan of them.  I much prefer the conversational
and sometimes tutorial style of standard Python documentation, to an
arbitrary API reference.  Sure, everyone writes documentation
differently, but you cannot expect one person to write all of the
documention.

With that said, I find reading the source to be very educational as to
how other people do things, but prefer to read /real/ source rather than
merely the interfaces to a particular module or class.  If one had
access to a reasonably decent editor (Idle has this feature), one could
open the desired module very quickly and easily; perhaps even faster
than looking up the documentation.  If one's editor had a heirarchical
listing of classes, functions, etc. (Idle also has this feature, though
it could be a bit better), the opening would produce pydoc-style
documentation on the fly.

Also considering that sites with pydoc documentation exist, would it be
sufficient for you if there were a link from every module page to its
equivalent pydoc reference?


 - Josiah