ClojureDocs are also interlinked and I think in an even more interesting way - any other vars that appears in the Clojure core source are linked to. A great way to understand how the core of Clojure is interconnected.
Racket's docs are good but it could use more styling. You've done a good job w/ that with Atomo.
shows that it's a Ruby+Rails app. RoR is a good choice for this kind of thing, but it would be slightly slicker if ClojureDocs had Clojure under the hood.
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.
To be fair that's the official docstring for defn. When you browse over to the docs for def (http://clojuredocs.org/clojure_core/clojure.core/def) the official docstring tells you to go look it up on clojure.org:
Please see http://clojure.org/special_forms#def
I believe this odd behavior is because Clojure's special forms are written in java and thus don't have easily parsed .clj source for the automatic clojure doc search tools.
The thing I love about Haskell's documentation is that it usually includes the full highlighted source code, all nicely linked. That's tremendously useful when you're diving into new code.
- smart way to deal with changes over multiple revisions. Functions are updated and comments are either deprecated or it's a new page.
I think one should work on something like stackoverflow but for documentation. Where you could supply some sort of parser for your specific programming language but have something uniform with all the basics.
I feel like pythons docs are hard to use, its difficult to just look up a method quickly also the search feature never seems to be very accurate for me. I will give the python docs credit when it comes to supplying good examples though.
I appreciate that they include all of the built-in functions in the same root directory as the remaining batteries-included modules.
The only wonky one for me now is the documentation for formatting strings, since it's documented in the "strings" module, but it's not dependent on the strings module.
The classic example of where this actually works well is in the PHP docs. Yes, you get idiots, but you also get good, real-world examples of a wider variety than the original documentation authors would have been able to produce. It's about the only thing I missed when I jumped from PHP to Python.
I think the Django Book's approach to this is really good as well, where the moderator overhead is implicitly taken on by the documentation authors. That works for them because they treat the document as a project in itself, rather than as a by-product.
I has example code and comments. Just like http://php.net did and which gave it enormous popularity and ease of use. What the docs don't explain a comment or an example clear it up.
The clojuredocs author knows the site needs to become even better. I thank him for what the site already delivers.
I modeled Anatomy, Atomo's documentation system on it: http://atomo-lang.org/docs/core.html