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!
Another suggestion would be to split tutorials/examples apart from object references. For example, take a peek at the Python Decimal module docs: http://docs.python.org/2/library/decimal.html#module-decimal
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:
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.
$0.02