That needs more explaination.
This is a better example, I think: http://docs.python.org/library/csv.html
This is a better example, I think: http://docs.python.org/library/csv.html
For me, the best kind of documentation is self-documentation. I love dir and the various forms of introspection at the Python interpreter. However, the Clojure REPL story, being a Lisp, just makes the Python interactive introspection experience look pathetic.
The thing about interactive documentation is that I, at least, find it much more likely that I'll remember it. When I just read something it tends to be forgotten shortly thereafter.
Have you ever used ipython? Can you give an example of how it pales in comparison? Typing dir() or help() sounds awful, I hope no full-time Python developers do that.
import csv
csv.<tab>
csv.reader?
csv.reader??
(Moving to bpython solved most of these problem though, as it shows the docstring for a given function inline.)
Also, you end up spending a lot of time reading the docs and so a little typographical polish wouldn't hurt. The page is simply too wide.