Peter Seebach ([mailto:crankyuser@seebs.plethora.net?cc=&subject=The importance of documentation] crankyuser@seebs.plethora.net) Freelance writer 14 November 2003
Abstract: Computer documentation is shoddy, or more often absent. Missing information amplifies usability problems, leaving users stuck calling unfriendly technical support lines. In this installment of The cranky user, Peter Seebach explains what's missing in the documentation effort and why it is gone.
The injunction to read the documentation has a long and colorful history. Users are berated and insulted for not having consulted the documentation, but, in many cases, the user can hardly be blamed. The documentation is shoddy, incomplete, and badly organized, if it's present at all. Exceptions are becoming rarer and rarer.
As documentation decreases in quality, users stop turning to it. As users stop turning to it, companies stop trying to maintain it -- why bother, if the users won't read it? This line of reasoning is dooming the future of documentation to failure. Documentation is important and needs to be taken seriously.
A disturbing trend is illustrated by video games which ship with woefully incomplete manuals, relying on a separately sold strategy guide to include charts, tables, and other fundamental information. This reliance probably comes down to the financial implications of the words "separately sold." One sometimes wonders whether productivity software would have better documentation if the market for third-party books about it weren't so lucrative.
One of the most pernicious beliefs in the software industry is the belief that, if a program is well-designed or -written, it will not require documentation. Of course, this is laughable. The first Macintosh computers came with a thick book.
Now it's easy for us to laugh about a book which explained how to use a mouse. However, that laugh can be very misleading -- users were not just taught the basics of mouse use, but also the majority of the keyboard shortcuts and other techniques they could use. A user who read the early Macintosh manual came out of it able to use a Macintosh. Judging by the level of support activity in the Mac newsgroups these days, I guess that's not the case anymore.
Some documentation is actually pretty good. Apple's diagrams and instructions for memory upgrades and the like are second to none. But I see very little how-do-I-use-it documentation anymore.
This situation is much, much worse when it comes to application software. It may be reasonable to assume that most users can figure out how to use a mouse (not just use it like a microphone to order the computer around) or at least be taught how to use it. On the other hand, applications almost always involve a great deal of undiscovered knowledge and new material. Each application is doing a new kind of thing -- it requires that the user be exposed to its abilities in some way.
You'll occasionally see programs advertised as being "as easy as 1-2-3." The first step is always easy, and probably redundant. The second step usually easy enough. The third step...well, building the Roman Empire is as easy as 1-2-3: 1. Be born somewhere in Rome. 2. Decide to build an empire. 3. Obtain the fanatical devotion of a number of rich and powerful people who will hire the mercenaries to form the backbone of your unstoppable army, which establishes a huge empire by providing people with a substantially improved economic infrastructure which deprives them of the will to fight your armies.
That's just three steps, so it must be easy. Whenever I see the phrase "follow the prompts" in an allegedly short process, I cringe.
Potentially, online help could be better than documentation. It could be, but it isn't. First, online help generally seems that it is going to be better because it doesn't have to be ready for manufacturing as soon, so the company can put another week or two of work into it. Second, much online help is totally unusable due to a lack of organization, or worse, poor organization.
The all-time prize winner for unusable online help has to go to the Apple Guide, which made it impossible to learn about something except when you wanted to perform the action. You couldn't read ahead; that enforced the procedure and refused to let you read the next step of a procedure until you'd performed the previous step.
This kind of inflexible organization is incredibly bad. Think of all the procedures where you do something irreversible early on, only to find out much later that you can't complete the procedure or that your actions will have side effects you can't accept. If Step 3 is "format the disk" and Step 5 is "insert your install CD" and you don't have an install CD, well, too bad for you.
I'd love to say "it's hard to imagine what they were thinking" because it's great rhetoric. Unfortunately, it's not true. It's obvious what the helpdoc-meisters were thinking. They wanted a help system that held the user's hand, walked them through the steps they needed to do, and kept them from making mistakes.
People, that is not possible. Even if you grant the idea of making sure the user has done the next step of the procedure, it is no defense against a user who initiates the wrong procedure. And if you can't read ahead to find out exactly what a procedure does, it is difficult to imagine a user who won't initiate the wrong procedure at some time.
When I was working on a support tech team, we got a call from someone who had a hard drive filled to the brim with crucial data. This hard drive (and its precious cargo) needed to be installed in a new server. The user followed the instructions in the manual for adding a second hard drive. He called support the moment after he formatted the disk. In later releases, the documentation distinguished between adding an existing hard drive with data on it and adding a new dataless hard drive. Painfully, I wish we'd thought of it sooner. This was paper documentation, but the principle was the same (and the message clear): Users benefit from reading the whole procedure before starting.
Good online help exists. Online help which takes advantage of the medium can be a joy to use. The Sun Java API documentation is particularly outstanding. On the other hand, it's a 40-megabyte download, compressed. The massive size of this successful online help resource hints at a major problem -- most online help is not full reference documentation, but a smattering of likely FAQs, with only the most common or obvious answers.
The index is a lost art. The idea of the index is to list all the words that you might think to look under and then tell you where to look. In most modern computer documentation, any given concept is found only under one word. That sounds elegant and simple, but it is precisely the opposite of what an index should do.
Think about it! If I already knew the terminology for something, I probably wouldn't need the index. The index is for times when I'm not sure what you call it, but I can describe it in my own words. Those words should be in the index too.
Want to make a good index? Ask people to look things up in it, but require them to write down the words they think of before they look in the index. Now make sure all those words are in your index. You'll be stunned at the gaps this uncovers.
The lack of a good index can undermine even complete documentation. It's not enough to have an answer to the user's question; the user has to be able to find the answer.
Documentation is important. It's expensive, but probably less expensive than the technical support which is used as a substitute these days. Not all documentation is bad; some documentation is very good. However, many companies have stopped even trying to write it very well.
This week's action item: Go to a program you use a lot. Does it have documentation? Try to look something up in it.
Photo of Peter Seebach Peter Seebach knows what good documentation is and why it has flown the coop. Shame on you software and hardware companies, selling products without cogent instructions. Reach Peter at [mailto:crankyuser@seebs.plethora.net] crankyuser@seebs.plethora.net.