You’re better off going straight to StackOverflow.com.
That’s the current situation with many technologies, platforms, SDK libraries and command-line interfaces: the documentation is so badly written, or so poorly organized, or so skimpy, that you can safely skip it and just use Stack Overflow as your answer-it-all search engine.
Or, to put it another way, most SDK documentation has a low cache hit rate, which I call a measure of documentation efficiency. If the efficiency is less than about 50%, then you’re better off skipping the docs entirely, and fetching the answer directly from the collective main memory of SO.
And you may have noticed that SDK documentation falls into one of two extremes. Here’s my experience:
Much greater than 50% efficiency:
Decidedly less than 50% efficiency:
Unity3D is an extreme case; the documentation is near-horrible. In addition, the work effort of improving the documentation appears to be part of no one’s job description. I stumbled across a rather egregious error in the Unity3D documentation, submitted a bug report, and it apparently went straight to /dev/null. It begs the question: how can they get away with such crappy docs? The answer to that question can be found in a Dilbert comic strip from November 8, 1995. Scott Adams is prescient. I’ll let you enjoy this very helpful link on the Dilbert web site:
http://dilbert.com/strip/1995-11-08
That’s right. Why bother spending the time and resources to write, maintain, and update documentation, when you can simply wait for someone else to write a “Dummies” book? And that Dummies book, here in 2016, is called Stack Overflow.
There is another criterion for documentation quality, and it’s probably the most significant reason that Stack Overflow is so useful: I call it the Example Criterion. Simply stated: Would a comprehensive list of examples be more useful than the provided documentation? It applies to obtusely-written Linux man pages, and most understaffed open source projects.
You know you’ve tripped over this criterion when one of two things happens:
It happens when very long-winded documentation tells you what to do, or how to do it, but not both. The extended length of the documentation seems to be an excuse for why there are no examples, but the length is exactly why examples are so important. That’s why a man page can be so long, and so useless, simultaneously. It tells you everything, except what you need to know. Stack Overflow is all about examples. And counter examples. And it’s usually the example from the SECOND answer that really counts…
After a question goes up on Stack Overflow, the first answer is usually cut-and-dry: it’s the answer that you would have come up with, had you sifted through the documentation. The answer makes perfect sense. But the second answer is better. The second answer is the answer-behind-the-answer:
Chances are, your code uses deprecated functions / methods / syntax, and you don’t even know it. The reason is because things become deprecated faster than you can keep track of it. Even your smart IDE isn’t telling you about your old-timey syntax. If you are using HTML / CSS, it’s almost impossible to avoid using something that’s deprecated, without running through W3C validation. Linux is the worst: things become deprecated right under your nose, and the deprecated syntax turns into no-op functionality, without warning.
Happily, Stack Overflow is more nit-picky than any lint picker. It’s the reason I keep discovering things in my code that are deprecated. Certain categories of syntax are more susceptible than others. If you are working in the realm of jQuery / HTML / CSS, it’s likely that at least 2% of your new code is deprecated, until you fix it. It’s also one reason that normal documentation is written out-of- order.
User manuals are written in the wrong order.
They organize information into categories. Instead, they should have the most essential information first. What’s the most essential information? It corresponds to the questions that get the most upvotes on Stack Overflow. These most upvoted questions have a few commonalities:
Stack Overflow is not a crutch. It’s a natural corrective that has evolved to fix what’s wrong about how we learn about technologies and platforms.