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: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Behalf Of Christopher J. Bottaro Sent: Wednesday, May 11, 2005 11:51 AM To: python-list@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 -- http://mail.python.org/mailman/listinfo/python-list
