[gcr]

Haha, I actually really like how Racket does it and consider them a great example to follow:

- Racket's documentation is all on your local machine. Stuck without an Internet connection? F1, and you're searching your own documnetation index.

- Everything -- everything -- is hypelinked. If you see a blue word in a code example, even the ones on the front page of http://racket-lang.org/ , you can click on it and jump straight to that function's contract.

But I agree, I wish there were a better way to jump straight to examples when you're looking at a specific function's documentation. It's confusing having the completely separate "Guide" and "Reference" halves of the documentation with no links between them.

[brudgers]

My gripe with Racket's documentation is that there is no middle ground between tutorials designed to showcase features rather than explain how Racket does and doesn't work and computer generated auto-docs. The tutorials are more geared toward selling the language to beginners, while the rest of the documentation is bereft of illustrative examples and editorial discussion.