In the calculus of communication, writing coherent paragraphs that your fellow human beings can comprehend and understand is far more difficult than tapping out a few lines of software code that the interpreter or compiler won't barf on.

That's why, when it comes to code, all the documentation probably sucks. And because writing for people is way harder than writing for machines, the documentation will continue to suck for the forseeable future. There's very little you can do about it.

Except for one thing.

You can learn to read the source, Luke.

The transformative power of "source always included" in JavaScript is a major reason why I coined – and continue to believe in – Atwood's Law. Even if "view source" isn't built in (but it totally should be), you should demand access to the underlying source code for your stack. No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you're likely to find. This will be true forever, so the sooner you come to terms with this, the better off you'll be as a software developer.

I had a whole entry I was going to write about this, and then I discovered Brandon Bloom's brilliant post on the topic at Hacker News. Read closely, because he explains the virtue of reading source, and in what context you need to read the source, far better than I could: