I do agree, we would need examples in the documentation to add more value. It may be trivial to google in some cases but a real pain for some libraries which we use occasionally.

I still find it way more fun than PHP and I can’t wait until I’m as familiar with it as I am PHP

Sorry, I love Python a great deal more than PHP, but the shell docs are garbage. Your example assumes the user knows how to create a list and that a list has a reverse function. What the poster is talking about is for complete novices who like to discover functionality by using *search* terms. I have to agree with him that simply going to the PHP site or CFM and entering “reverse array” and getting the function you’re looking for is a lot easier than somehow magically knowing about Python lists and the list’s attributes.

@Others
Yes, I know about the interactive shell. I use that a lot when I am working on Python. But I don’t expect beginners to know about it. They need reference manuals. And what about Python developers on Windows? I think they are allergic to the terminal window

@Marc
> (2) grep? (from the shell)
I am not sure what you mean – how do you find the python documentation of a given function using grep? Which folder should I search?

As for not being able to search the documentation, have you every heard of:
(1) Google?
(2) grep? (from the shell)
(3) dir or __doc__ ? (from within the interpreter)

Your article can be basically summarized as ‘I don’t understand how to use python therefore it is flawed’. My honest opinion: I’d rather you didn’t write python because I may have to one day read the code that you write.

Unfair. I also prefer to read good documentation and on principle prefer more examples in the documentation without having to guess behavior from interactive experimentation.

As the editor of the quick reference card in the original O’Reilly Python book, I have to say the documentation hasn’t changed all that much in the 10+ years since the 1.0 Python release. Personally I think it’s actually fairly good — as someone says, it’s ratheer comparable to Sun’s Java API documentation — but it’s a little surprising how much the documentation would look familiar to a user of release 0.9!

It would be interesting to set up a wiki based on the documentation, see what changes users come up with, and use that as a clue as to what documentation in the official docs could use more work.

After a long debate with a co-worker we decided it was a virtuous circle problem. Which the PHP community set up a base standard for documentation and then continued to improve upon it. The python community set their base and while it might have improved, it designed for a _very_ different group of users.

Think of it this way:
* PHP is the current incarnation of Basic — so the documentation is targeted at that class of users
* Python is C so targeted at that class of users (aka, read the code luke)

Fundamentally, I want documentation that is more akin to PHP (or java) — Verbose, clear parameter and clear returns. Heck, the best part of the PHP and MySQL documentation is the user comments, where real code examples exist around the problems.

Just taking your “finding a function” example: have a look at http://docs.python.org/dev/genindex.html

I think you might be pleasantly surprised…