The Deal

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:

• jQuery, using their fast, comprehensive website
• JavaScript, with the extensive documentation courtesy of Mozilla.

Decidedly less than 50% efficiency:

• HTML / CSS. There is nothing readable, definitive, or practical. Nothing works the way it’s described.
• Most Linux man pages
• LibreOffice
• Unity3D

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.

The Example Criterion

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:

1. You become so exasperated at the impenetrable text, that you find yourself thinking “Screw this: just show me a bunch of examples, and I’ll reverse-engineer the documentation myself.” In this case, it would, in fact, be easier to piece together how the underlying black box mechanism works from a series of stimulus/response examples, rather than from the documentation that purports to tell you directly.
2. You slog your way through an obtuse Linux man page, get to the end, and then realize “Oh shit. No examples. I’m f*cked.” There are always expletives involved.

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…

It’s the SECOND Answer that 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:

• It’s the answer that also handles corner cases that you haven’t thought about. If it’s a JavaScript question, you’ll get an answer that deals with values that are null, or undefined, or NaN. Or properties that are named “undefined”.
• It’s the more elegant answer. If it’s a Python question, the second answer will be more Pythonic.
• It’s the answer that incorporates best practices. It might be a more thread-safe or exception-safe.
• It’s the non-deprecated answer, and that’s the next big value-add of Stack Overflow

2% of Everything you are Doing is Deprecated

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.

Out-of-Order Documentation

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:

• They reveal that it’s almost as important to know what you can’t do with a technology, as opposed to what you can do. When is the last time that you read documentation with a chapter entitled “everything you can’t do?” Well, never. But the reality is that knowing what you can’t do will place clear bounds on the capabilities of a technology, and you’ll understand it better.
• Most technologies have commonly misunderstood, non-intuitive, or counter-intuitive aspects. It’s often important to know about these first, before you try to do anything. But most documentation doesn’t have a chapter titled “what not to do,” and that’s where Stack Overflow supplements the documentation. Deprecated syntax falls into this category.

The Bottom Line

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.