When we think of “bugs” most of us think of bugs in the code. But there’s all kinds of bugs out there, and one of the ones that annoys me the most is bugs in documentation.

Bugs in documentation?

Yep. Badly documented, under documented, erroneously documented, misleadingly documented. All of these lead to a similar result: the person can’t use the software.

But that’s not a bug!

Sure it is. If you have an error in the software, the user can’t use it. If you have an error in the documentation, the user can’t use it.

I think developers and programmers tend to lose sight of this fact, because they are not only capable of tinkering under the hood, they are used to doing so, and like doing so. That’s partly why they are developers and coders in the first place.

And if their audience were likewise developers and coders, the documenation wouldn’t be an issue (well, theoretically; there are always killjoy developers and coders like myself who side with the users on this one). But the problem is the audience is generally a wide set of folks who not only can’t tinker around with things, they don’t want to. They don’t have the time for it, there are other much better things they can do. So they’ll drop it, move on to something else, or even worse, use a competitor’s product that is more intuitive and/or better documented.

Incomplete documentation is an obvious source of problems and occurs far too often (recall how Selenium fails to document exactly how to install it, and Clipmarks fails to note that their icons are in the custom toolbar in their “easy 1-2-3″ setup). Worse yet, if some feature is not properly documented, the user may never utilize the full power of the software, and perhaps move on to another that does have the feature, under the mistaken belief that it does not exist in the current software.

I’ve seen cases where documentation existed, but was not updated to reflect changes in the current version. At worst the documentation becomes incorrect, at best, misleading.

Sometimes documentation is just badly written. It needn’t be obvious. Consider a common example, in which each option and each command is separately listed and described. It’s complete, it covers all the possiblities, nothing has been left out…but the average user still can’t figure out how to make use of it. Why? Because the documentation fails to cover scenarios. If there aren’t sections explaining how to use the software for various different purposes, a user may still be completely lost if it isn’t clear what approach should be taken.