4 ms·

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 th

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.

reikonomusha 8y ago
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.
- flavio81 8y ago
  >I think Lisp’s “the source is the documentation” (with comments and doc strings) is a huge boon. True. 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.
karmakaze 8y ago
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.
- fiddlerwoaroof 8y ago
  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.
  - fiddlerwoaroof 8y ago
    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.
  - karmakaze 8y ago
    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.

reikonomusha 8y ago

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.

flavio81 8y ago
>I think Lisp’s “the source is the documentation” (with comments and doc strings) is a huge boon. True. 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.

karmakaze 8y ago

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.

fiddlerwoaroof 8y ago
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.
- fiddlerwoaroof 8y ago
  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.
- karmakaze 8y ago
  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.