I modeled Anatomy, Atomo's documentation system on it: http://atomo-lang.org/docs/core.html
Racket's docs are good but it could use more styling. You've done a good job w/ that with Atomo.
https://github.com/zkim/clojuredocs
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.
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.
Please see http://clojure.org/special_forms#def
The speed and ease at which I can search the erlang docs for specific functions is the best I have found.
e.g:
- stack overflow running on top of that to rate comments + index questions asked on functions
- smart snippet indexer. Examples rarely cover everything
- 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.
Docs > Library Reference > Built-In Functions (browser search for function)
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.
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.
Now, there's an argument that it should have a syntax reference as well, but that doesn't seem to be the goal (yet).
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.