I'm just glad that Clojure has a good community driven documentation site that's approachable for newcomers. As far Python documentation goes I've never considered it particularly useful.
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.
> However, the Clojure REPL story, being a Lisp, just makes the Python interactive introspection experience look pathetic.
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.
I have used ipython. How do you easily reload arbitrarily nested modules? How do you easily redefine only one function in some module and have that change be reflected globally?
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
Python's docs are reasonable, but could be better. I don't like the left-hand contents, I find it breaks the flow. Wikipedia's inline contents seem far more intuitive. I'd like to be able to jump to specific functions.
(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.
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.