Hacker News new | past | comments | ask | show | jobs | submit login

I find that I almost never read documentation in languages like Common Lisp and Clojure for two reasons:

1) documentation is often unmaintained and reflects the state of the library at some point in time, but not the current API. But...

2) even when there is good documentation, it’s often easier to just take a code example and then use the excellent jump to definition and other tooling to understand how the example works than it is to read the definition: in part, because there’s always a repl available in these languages and it’s much easier and quicker to run mini-experiments on the language at the repl than it is to read the documentation and translate it to code.

I think Lisp’s “the source is the documentation” (with comments and doc strings) is a huge boon. I usually figure out how something works faster and more accurately than, say Ctrl+F’ing some Python Sphinx documentation.

>I think Lisp’s “the source is the documentation” (with comments and doc strings) is a huge boon.


At first i thought "Damn, there is little documentation on those Lisp libraries", but as the months passed, I understood that often code was very readable, and the fact that documentation strings are integral to the language is also a good thing.

My point was about documenting the home-grown domain specific language. Do you think it also wouldn't be useful and better to just read definitions? Doing mini-experiments might not be as simple as it could depend on other parts you have yet to look up, etc.

My experience is that reading source code is often an easier way to figure out how something works than reading documentation: especially in an environment with good jump to definition and a language that doesn’t impose very much boilerplate and meaningless syntax on your code.

In a similar vein, I’d rather see your test-cases, nicely formatted, than your documentation: you can execute a test case to check that it still is true; you cannot execute your documentation.

I agree that learning from examples is very powerful. Good language documentation in addition to defining what each construct does, also provides examples which should be more concise than a random ones found in a codebase.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact