1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)
2. Whitespace (section 2.1)
3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)
4. All functions, types, classes... both globals and stdlib modules are documented in http://docs.python.org/library/index.html#library-index
5. All parameters? Documentation should already have these.
6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented
7. Default values and their meanings are pretty much always documented
8. I don't know what flag values are, but if they're just parameters they fall under (5)
9. Return values and exceptions should always be documented
10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.
A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed.
So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python libraries. There didn't appear to be the equivalent of RubyGems or Bundler. There did seem to be 2-3 different ways of managing them (eggs?), but just getting those programs working on my local system wasn't liking me either. Googling for "Using Python libraries" didn't return much useful- nor did "Installing Python Libraries".
I'm still unclear what the standard method for managing these is. When I checkout a Ruby thing, I just type 'bundle install' and all is fine then.
Yes, the technical docs were fine- but the baseline "how do I get this damn stuff, working!?!?!" wasn't.
If only this was just a documentation issue. Alas, the reason is that there is no standard method. Here's a short practical article on how to install Python packages and get on with your life: http://dubroy.com/blog/so-you-want-to-install-a-python-packa.... For a longer historical perspective of this whole clusterfuck check out http://lucumr.pocoo.org/2012/6/22/hate-hate-hate-everywhere/
1: http://pypi.python.org/pypi
Edit: There's also the official documentation page called "Installing Python Modules" which covers the last of those three methods: http://docs.python.org/install/index.html
Edit 2: and from the FAQs, http://docs.python.org/faq/library.html#general-library-ques...
For now, you can get most of the way by trying 'pip install X' or 'easy_install X', but there are important edge cases.
It's being worked on for Python 3's next big release, last I heard.
If you ask me to do the same in Ruby, I'd probably be lost too.
Most of the times I'm looking at CoffeeScript to just figure out what it compiles to!
There's a critical gap between the expectations of Ruby/Java programmers of how to write Python and the way Python programmers behave. I think it really is cultural, to an extent. The Java programmers look for Java-style documentation, with classes and methods and lists of exceptional conditions. The Ruby programmers look for Ruby-style documentation, with lots of diversions into the "why" of things and the context, possibly with pictures of foxes.
A Python programmer would consider the Java docs needlessly detailed and the Ruby docs a bit fluffy and not to the point, but after all, it is just a matter of viewpoint, community goals, and culture. There's also the issue of installing packages in Python, which can be a bit of a bummer, but I've never had a problem downloading a Python package from some site and following the directions.
Reference manuals are still nice to have of course for clarifying edge cases and solving language lawyer disputes. However claiming that they are a superior learning and time-saving tool than the learn-by-example techniques is way out of touch with how most people actually learn.
If you are only doing your own product using Python libraries, then certainly you don't.
But it seems like there's a big trend now to just "get things out there" and that good documentation isn't "cool" anymore, kind of like braces in syntax.
Examples of good docs: PHP, jQuery, MySQL. (The first two sites include user comments too, which make things even more useful.)
Examples of terrible docs: Python, CoffeeScript (the worst)
I can at least understand insufficient docs for pre-1.0 versions when the implementation is changing constantly, but when something has been around for more than a year, it's just inexcusable.
I don't want a "getting started" guide that gives a bunch of examples. I don't want to type in the console to find out what methods an object has.
I want a friggin' reference manual, that includes (as applicable) syntax rules, exact rules governing whitespace, orders of operations, all functions, all parameters, parameters passed to a callback (why are these forgotten so often?), default values, flag values, all possible return values, specific exceptions that can be thrown, what input parameters result in undefined behavior.
Really, it's just not that hard. It may be grunt work, but if you'd rather make your users waste a cumulative 25,000+ hours figuring things out, rather than you spending 100 hours of your own explaining things, I just can't have respect for your product, no matter how otherwise amazing it is.