Python Documentation (should be better?)

[Shi, Jue]

I agree. The PHP manual is really good, especially the examples and user
contributed notes.
I think that's why we need the reference manual most time. It help you to
get started on that particular function as well as hint you the trick and
trap.

I really wish Python manual gets better on these two areas.
Is it feasible to write a program to search the mailing list for example and
discussion related to particular function and archive it right under the
session of the manual. Anyone want to start this project?

Maybe a mailing list or forum people can contribute example and notes?

Just a thought.
Jue


-----Original Message-----
From: python-list-bounces+jue_shi=or.mxim.com at python.org
[mailto:python-list-bounces+jue_shi=or.mxim.com at python.org]On Behalf Of
Christopher J. Bottaro
Sent: Wednesday, May 11, 2005 11:51 AM
To: python-list at python.org
Subject: Python Documentation (should be better?)


This post is just the culmination of my thoughts and discussions with my
coworkers on Python.  If you are not interested, please skip over it.

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).  I chose to do all mine in Python because I'm a
huge Python fan boy.  Naturally, I tried to get my coworkers to try Python. 
I made an agreement with one:  I write one of my modules in PHP and he will
write one in Python.

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.

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()?

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!

Don't get me wrong, I love Python.  The language itself is second to none (I
haven't tried Ruby yet), but this experience has left me wondering about
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.

What do yall think?

-- 
http://mail.python.org/mailman/listinfo/python-list