[dgallagher]

A navigable list of objects, functions, and methods would be really nice, something like this (preferably complete): http://api.rubyonrails.org

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:

    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.

$0.02

[zanny]

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.