
How a programming language documentation ought to look like: clojuredocs - albertcardona
http://clojuredocs.org/clojure_core/clojure.core/defn
======
vito
Pales in comparison to Scribble, Racket's documentation system. Filled with
examples, all interlinked: <http://docs.racket-lang.org/reference/define.html>

I modeled Anatomy, Atomo's documentation system on it: <http://atomo-
lang.org/docs/core.html>

~~~
swannodette
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.

------
kylecordes
ClojureDocs is quite nice. One thing I noticed is that a peek in its source
code:

<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.

------
fisadev
That needs more explaination.

This is a better example, I think: <http://docs.python.org/library/csv.html>

~~~
swannodette
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.

~~~
bretthoerner
> 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.

    
    
        import csv
        csv.<tab>
    

Blammo, tab completed dir().

    
    
        csv.reader?
    

Blammo, docstring, method signature, and more.

    
    
        csv.reader??
    

Blammo, code for the method.

~~~
swannodette
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?

~~~
pig
What has that got to do with _introspection_?

------
torme
I agree that the examples are nice, but it'd also be awesome if there was some
explanation as to what that function did.

~~~
dpritchett
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.

------
smackfu
My favorite is the perl ones, which have tons of very useful comments giving
examples.

------
jedbrown
Hoogle is pretty cool:
[http://haskell.org/hoogle/?hoogle=m+a+-%3E+(a+-%3E+b)+-%3E+m...](http://haskell.org/hoogle/?hoogle=m+a+-%3E+\(a+-%3E+b\)+-%3E+m+b)

~~~
pjscott
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.

------
sz
Io's layout is still my favorite:

<http://www.iolanguage.com/scm/io/docs/reference/>

------
roder
My favorite docs are <http://erldocs.com/>

The speed and ease at which I can search the erlang docs for specific
functions is the best I have found.

------
protomyth
I am starting to wish for ePub versions of the docs. That would let us use our
eReaders/iPads.

~~~
gregwebs
Just released for ruby. <http://tenderlovemaking.com/2010/04/12/rdoc-on-your-
ipad/>

~~~
draegtun
Ditto for Perl: [http://blogs.perl.org/users/olaf_alders/2010/07/icpan-
cpan-o...](http://blogs.perl.org/users/olaf_alders/2010/07/icpan-cpan-on-your-
iphone.html)

------
hbt
It's good but it could be better.

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.

------
swah
Not a great example of content, but the search here is really fast, I'd love
something like this for clojure core + contrib: <http://ukijs.org/docs/>

------
afhof
Trying to select the code includes the line numbers.

------
alexyoung
s/How a/What/

------
honza
I disagree. It doesn't look very well-organized. Python's docs are much
cleaner.

~~~
regularfry
Python's docs lack a place for comments, which is a shame.

~~~
codefisher
It would just turn into a place where nobs ask questions, and you really want
that done in the proper place. And you also have the moderator overhead.

~~~
regularfry
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.

------
albertcardona
It has a search function.

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.

------
gcb
i read that page and i'm still clueless as to the need of & in the argument
list...

~~~
regularfry
That's because it's a library reference, not a syntax tutorial.

Now, there's an argument that it should _have_ a syntax reference as well, but
that doesn't seem to be the goal (yet).

