Python Documentation (should be better?)

[John J. Lee]

"Christopher J. Bottaro" <cjbottaro at alumni.cs.utexas.edu> writes:
[...]
> At my work, we are developing a product from scratch.  It is completely
> modular and the modules communicate via SOAP.  Because of that, we can
> implement individual modules in any language of our choosing (so long as
> they have good SOAP libs).

Oh dear!  Have fun <wink>

[...]
> After we were done, we talked about the pros and cons of the languages. 
> Funny, the con of Python (documentation) is PHP's strong point.  The PHP
> manual is extremely easy to navigate and its search feature works great. 
> Contrast that with Python, where you have to use "the tutorial" as the
> manual.  Also, the tutorial is just that...a tutorial, its a NOT a manual. 
> Its not organized like a manual and its not comprehensive like a manual,
> hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.

Did they renumber it at some point?  In my copy: "7. Optional
Operating System Services".

Ohh, you mean the Language Reference?  I've been working full time as
a Python programmer for over a year (and using Python for many years
before that), and I've certainly never sat down and read it start to
finish (nor even read the whole thing in pieces, over the years).

[...]
> Now for the real kicker.  Some of the module documentation doesn't even list
> simple use cases or even the entire API.  When my coworker came to me with
> this complaint, my response was "oh, just load the interpreter, import the
> module and call dir() on it.  Then instantiate some objects and call dir()
> on them also".  My infatuation with Python had kept me from realizing the
> sheer ridiculousness of that method to learn to use an API.  Needless to
> say, my coworker's reaction to that statement snapped me out of it.  But
> its the truth.  How many of you learn a module by starting the interpreter
> and "playing" around with it and using dir()?

I don't.  dir(), the interactive prompt, module inspect &c. can all be
very handy at times, though.


> The next complaint isn't really about documentation.  Why isn't there a CPAN
> or PEAR for Python?  So many times I've search for a module, not found it,
> started to write it myself, then later stumble across it on Google...ugh!

Fair point, but PyPI (pypi.org) is growing (and now very easy to use),
and the Vaults of Parnassus was still there last time I looked.

[...]
> the future success of Python.  Even I, a huge Python advocate, has started
> to use PHP more often simply because I can find well documented,
> semi-official modules very easily and learning PHP is a breeze with the
> awesome PHP manual.
[...]

I don't recognize the problem with basic language features or module docs.

There is perhaps a problem with docs for language features on a more
advanced level than you complain about, though.


John