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

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