A recent mailing-list discussion has raised my hackles about documentation. So at the risk of offending all the tech-writers out there, let me restate my thesis: Documentation Sucks!

I’m not just saying that because I’ve been very slow to provide substantial documentation for my two in-house applications. The only thing worse than lack of documentation is too much documentation. It’s too often a sign of design failure in the application. Documentation is insidious. As soon as it reaches a certain size, it seems to become a black hole for “explaining away mistakes.” The new feature is completely unintuitive, but completed by the deadline? It’s OK, just stick a note in the documentation! Then you end up with a big junky piece of unusable music composition software, or ridiculously ill-behaved spreadsheet app.

When you install a piece of software, its value can often be measured by how much you can get done without looking at the manual. I’m not saying there shouldn’t be a manual (except in rare cases), but it shouldn’t be necessary for your first conversation with the program.

Who here has read the manual for Safari? The Dock? Address Book? You haven’t? How do you get anything done?! Do they even have documentation? Sure they do, but they’re not mammoth, and they’re mostly there to feed the public’s addiction to documentation. Take Address Book. If you open its help book from the Help menu, you’ll see the the documentation is split up into four fairly discrete sections:

The first section is sort of a “release notes” for consumers. This is valuable, but hardly needs to be in the manual. In fact, it’s probably the last place I’d look for it. For a paid product, I would expect to see it on the web in marketing information. This is the type of information that Apple gets to include in the documentation because they push their applications to us for free. We don’t have to decide that there is a true benefit to us before deciding to upgrade to them. So they have to sell us on the application after we already have it!

The second section is also essentially marketing information, but packaged as a “getting to know your new Address Book” type section. There is some helpful stuff in here if you’re looking to do advanced features like syncing, but in the “obligatory documentation” department we get items like this:

“Oh that’s what the little oval box with the magnifying glass in it does!” Don’t get me wrong, users need to know this! But if every application takes responsibility for explaining every UI convention to every user, there will be a whole lot of reading and whole little of doing.

The third section: “Solving Problems” is really the holy grail for users. It’s both the only section users really need, and the only section that can’t be written without their help. Until your users present problems, you can’t succinctly elaborate on them in the documentation. This section, in addition to being the only useful one, is the one that you want to focus on eliminating as revisions to your application are produced. Your bug list and your “Solving Problems” list should be pretty well in sync.

When’s the last time you needed a manual to watch a DVD? Is there a manual? There’s a complicated (sometimes infuriating) user interface that provides access to a sometimes large number of features. The UI is in fact much less standardized than a typical computer UI. Yet there’s no manual. Why? Because the penalty for making a mistake is small and the consequences of an action are clearly communicated to the user. The only thing you need a manual for on most DVDs is to find the secret, hidden “easter egg” features. Unfortunately, many applications on the Mac treat all features like easter eggs. Want to copy text from one paragraph to another? “First, go to page 182.B of the manual. Now, while pressing control, shift, and caps-lock, turn around 3 times while fingerspelling ‘Paperclip’ with your free hand. To learn more, please turn the page.”

For that matter, when’s the last time you read a manual for a hammer? Pair of pliers? Your desk? The rug on the floor? For which tools in your life do you find high value in the manual? Is it valuable because it’s required to use the product or because it enhances the product? If it’s required then don’t you resent the manufacturer?

A great example of an extremely complicated, extremely dangerous application with a minimalist manual is the automobile. Most of us trust ourselves implicitly to step into any automobile manufactured in the past 60 years and get from point A to point B with relative ease and absolute safety. Sure, there’s a manual for your car, but have you ever looked at it? I’ll tell you what it says. It has some ridiculous stuff like “This is a key. Keys make your car start. Please don’t pump the gas while the car starts.” OK, that’s filler, but the manual is still thinner than most software manuals. If you’re lucky, it also has some really useful Solving Problems stuff like “Oh Crap. Your battery’s dead. You probably thought you’d never have to do this, but here is how you jumpstart a car.” (Some automobile manufacturers, realizing that the Solving Problems list is also a bug list, have added features to their cars like backup batteries to automatically jump start the main battery when it dies. Nice!)

Nowhere in your car’s manual does it say “vehicles approaching at 60MPH should not be collided with head-on.” We are “car literate,” so we know these things without having to be told. In fact most of what we know about driving and cars we learn by observation and experience – we are exposed to driving from a young age and become confident about our understanding of the complex system. Sure there is training, but once you learn how to use one car, you are in a good position to use any car – and most importantly, these pre-requisites are not the car manufacturer’s responsibility! This is how computer software should be. Customers who are minimally computer literate should be as comfortable stepping into your software’s trial period as they are stepping into a rental car. As our world becomes more and more computer literate, it’s becoming an insult to explain things like “This is a search box. Search boxes are for searching.”

Car companies save a lot of paper because there isn’t an expectation of a phone-book sized manual when you buy a new vehicle. The software industry isn’t so lucky. One of the biggest ways in which documentation sucks is that parts of the computer-using masses (particularly those who still feel a bit cautious about getting behind the mouse) have been conditioned to expect manuals for everything. And big manuals, at that! If we don’t get a big manual from the manufacturer, we’ll pay some book publisher for a big fatty.

Two decades of crappy software and obligatory documentation have conditioned users to expect the worst. We need to wean the world off of manuals by proving to them that we too can get them from point A to point B without getting injured.

This entry was posted to Usability. Comments are closed. Thanks for reading!