The problem with python's website was never that it wasnt "Sexy" enough to attract newcomers. Its that the documentation was never as well written or well organized as other languages/libraries like ruby and jQuery.
All the information is there, but it isn't organized very well. There's a tutorial, overview of Decimal and its methods (with tutorials mixed within), and various "notes" sections. It's all mixed together, and confusing for a new user.
Personally, I'm more of a fan of this type of structure:
1. API documentation. No how-to's.
2. "Guides" and How-To's
API documentation is like a dictionary. Succinct, to the point, not littered with "Here's how you write a sentence with this word" examples.
Guides/How-To's including examples, introductions to use an object, spell out caveats, etc... This should get wordy when needed.
Both could have links to one another. For experienced coders, you'll mostly just use #1 (which fits great in a navigable list). For newbies, #2 will teach you how to do things.
Agrees on this. Sometimes you don't want the tutorial or book, you just want the reference guide of one liners saying what the thing is, at least for the proficient programmer. If I come back to Python from a few months on some C++ project and have to spend 15 minutes looking up how to use their JSON api because I have to dig 90% of the time to find callables the docs fail.
The lack of a Javadoc / Qt ref / cppreference (I love that wiki) module / function list makes just searching for something you know exists and just need the method name a pain in the butt.
The documentation is beautifully written and perfect for learning, but it doesn't support the quick-fire referencing I, and I presume the other detractors, have grown to expect.
Contrast the first Google result for "python dictionary" [1] and "java hashmap" [2]. The Python result tells you about every data structure and does so in a story, the Java one gives you what you want and little more.
The first result is the tutorial - the second result is the comparable API documentation, although unfortunately you need to find the right section of the page after clicking through. Like the Java doc, it has a prose introduction followed by a list of methods.
Overall, I think you're right that the Python docs aren't optimal for quick fire referencing. I think we tend to use some form of introspection to examine methods, function signatures and docstrings. For instance, I keep IPython open and use tab completion and the 'foo?' syntax to find the details I need.
I also think the docs are pretty good. However, the one thing I would absolutely LOVE is if they added a table at the top of every page that has functionName and return Type (like so many other languages do).
The thing that irks me about the docs now it that they're almost too in depth. Sometimes, when I just need to get a quick refresher of what function X does, it takes me nearly 45 seconds to just find the thing. Ctrl + F doesn't help because the docs are so verbose that searching for one thing usually results in 20+ hits or references on the page.
Just a little table like the Java docs, and I'd be pleased as punch!
I'm a Rubyist but I find that curious because the more common public complaint seems to be that Ruby's documentation isn't as good as Python's. (And its official site is rather tired, to say the least.)
I really liked Python's documentation. I read the tutorial and it got me up and running really quickly, and whenever I had a problem or needed details of the arguments it was an invaluable reference.
Clearly, not everyone thought so. What did you not like about the docs?
It's nice to learn from, but if you already know what you're doing and you just forgot the arguments to that one god damn method, it's pretty irritating to actually find the arguments to that one god damn method.
I find Python's online documentation to be fantastic. It's probably the best online documentation I use. I'm really curious what about it you find lacking.
If Python's documentation is a "problem", then IMO the devs should continue doing problematic things. What in particular do you find lacking about the documentation? I've never heard this complaint before.