June 1996

Manual Labors
12 Steps to Better Documentation

by Paul D. Lehrman

Just this month I received a product that was accompanied by, hands down, the worst documentation I have ever seen for a piece of electronic equipment. Besides lacking any coherent information on how to configure the thing, how to use it, or how to integrate it with anything else, this "user manual" was so lame that it took me two days and three calls to the distributor before I realized that a) three parts were missing and b) two parts were completely non-functional.

This is an extreme case, to be sure, but it's no lie to say that, in general, documentation in our industry stinks. As my editor puts it, writing about the state of manual writing in the pro audio field is kicking a man when he's down. But it doesn't have to be that way. Good user manuals (and such things do exist) can make a manufacturer's customers feel very good about its products, and make them eager to check out the next ones. Taken a step further, documentation can determine whether we assimilate all of the wonderful and initimidating new tools that are coming at us at warp speed, or whether we're going to run screaming out of our studios and off to the hills of Vermont to tap sugar maples.

It costs money, but only a small fraction of what r&d costs, and the payoff can be substantial--although that payoff is measured more by what doesn't happen than what does: the more information in the manual, and the easier it is to find, the fewer tech support calls users will make, and the less time they'll spend on hold while the manufacturer's overworked support staff gets their ears chewed off by other angry customers, and the fewer clients all over the world will steam quietly while the studio is down. Everybody benefits!

Whatever you've just picked up, whether it's a new compressor, a console, a sampler, or the latest DSP software, you can always use some help in getting up to speed with it. Every piece of new gear has some quirks that you're not going to find out about, simply by playing with it yourself. And if it's a really complicated piece, like a DAW or multi-effects processor, then it could take you weeks to figure it out on your own. Even then, like Harpo Marx discovered when after a dozen years playing the harp in vaudeville he finally got around to consulting a harp teacher, you may in the long run find out you've been using it all wrong.

Unfortunately, many manufacturers forget this. Given the insular nature of the development process, they forget that the rest of the world was not in the room when they made all those brilliant engineering and design decisions. They don't realize that they have to explain to users what all this stuff is and does--they won't get it by osmosis.

Now, I'm not exactly neutral here: writing manuals is one of the things I do for a living. But I'm not selfish about it, and I appreciate a good manual even if I haven't written it. So in the spirit of this generosity, here are some rules I follow when I'm working on a project, which may benefit some others:

Put the important stuff up front. The first computer-music system I bought came with a 200-page, non-indexed, typewritten manual, with the installation instructions stuck in an Appendix in the back. I slogged through a dozen chapters, unable to actually do any of the things I was reading about, until I happened to stumble across them. Don't force me to search for crucial information: if your device has quarter-inch outputs, let me know whether or not they're balanced, and what their operating level is, and how to change it. If I need to format a tape or disk before I record anything, tell me how to do that right away. If you make computer software, keep in mind that, believe it or not, some of your customers might want to use their computers for some purpose other than running your software, and if there's a program or system file that I might already be using that is incompatible with yours, don't bury that info in a "Read Me" file--make sure that checking for incompatibilities is part of the installation process.

Make the user comfortable. If I've bought a new toy, I want to get going on it right away. Not just because I have the patience of a four-year-old, but because I want to feel good, as soon as possible, about having spent all that money. Give me an introductory tutorial that will walk me through some of the more interesting and unique things your product does. I don't need to be told everything about what I'm doing while I'm doing it, I just want to see what's cool. Once I've had a peek at the highlights, I can relax and spend time learning the thing more thoroughly.

Have a special section for upgrades. If a substantial portion of your user base has worked with previous versions of your product, make sure there is a section in your manual for them that describes all the changes and new features. Don't force them to pore through 300 pages of manual just to find out that the "Drop/Non-drop" switch has been moved from menu A to window Z.

Use tutorials. Even beyond introductions, tutorials are by far the best way to learn about new tools. To deconstruct the proverb, tell a man all about the evolution of aquatic cordates, the physics of barbed steel, and the nutritional value of segmented annelids, and you'll put him to sleep: show him how to put the worm on the hook and throw it into the water and he'll have trout almandine all his days. Telling me how a feature works is far less valuable then telling me how to use it, and the best way to do that is through example. No, a tutorial can't cover every single feature of a product in depth, but it will get my excitement level up. It will stimulate my mind, and make me far more receptive to learning. Then I'll be happy to dig into other features, no matter how they're presented.

Make it easy to find things. Two words: Good Index.

Use in-context help, but don't depend on it. On-screen help menus or display pages are great when a user has to find out something quickly. The text that appears there is just as important as the printed text, so spelling errors or weird grammar are no-nos. But unless you're building a true hypertext engine for it, on-screen help can't go into nearly the same depth as a book, and so you shouldn't consider it a replacement for the printed manual.

Anticipate how things can go wrong. Components fail. Cables break. Software files get corrupted (usually during the installation process). If you provide me with running checks on everything as I put your complex system together, then when something does happen, I can figure out where it went wrong. And when I call your tech people up, I can do something more constructive than whine, "It's not working!" Also, people can hook things up wrong, and do things in the wrong order. Try to make allowances for that (we may be idiots, but we pay your salaries!), and walk me carefully through particularly delicate operations. Lots of "right and wrong" drawings can help. I never, ever again want to see the words, "Before you do the procedure described in the previous paragraph..."

Don't be afraid of redundant information. Some manual writers think it's heresy to put the same information in more than one place, and so their documentation is full of cross-references: "Before you save a file, see the backup instructions in chapter 14, the installation guide in chapter 3, and the troubleshooting grid in chapter 21." Whenever I see that, I'm tempted to run to my Xerox machine and copy all the referred-to pages, and stick 'em in all the sections where they're referred to. It doesn't cost much more to repeat the relevant paragraphs of those chapters where appropriate, and it will save me and my kind lots of aggravation (and keep the manual a lot neater).

Knock it off with the thousands of inserts. Speaking of neatness, if I really want stray slips of paper lying all over my floor, I'll buy some magazines and shake out all the damn subscription cards. I can't believe how many cutting-edge companies, whose products constantly require upgrading, put their manuals in bound books. This means I'm constantly forced to deal with a flurry of multicolored, easy-to-lose "Read this now!" sheets, or lengthy "Read me" disc files that refer to stuff about which I have no idea, and when I do get to the level of understanding them, I'll have totally forgotten they're there. Looseleaf or spiralbound manuals allow for easy editing and expansion--and they have the added advantage of being able to lie flat on a console or copy stand (as long as you don't use a three-inch binder to hold a quarter-inch's worth of paper--that's pretty dumb, too). Plus, they often have pockets where I can store my key disks and all those upgrade disks you're bombarding me with.

Use native English speakers. I'm not a linguist, so I can't tell you why this is, but Japanese people seem to expect very different things from their documentation than Americans do. It's not just a language thing: the thought processes themselves are, apparently, utterly different. I once read an article by a North American who had just been hired by a Japanese company to do their English documentation. The first thing he did, he said, was translate the Japanese manuals. Reading that, I knew he wouldn't last long--and he didn't. The stuff he was coming out with was no more appropriate for the American market that what his predecessors had done, although the grammar was better. What he needed to do was chuck the Japanese manual in the garbage, sit down with the engineering spec and the designers, and start from scratch. No matter how much English they've taken in college (and some of them seem to flunked it in high school), Japanese writers don't know how to construct a manual for users in the English-speaking world. But even though we are their largest market, a lot of companies in Japan (and the other Asian and some European countries are just as guilty) just don't get this--and yet they wonder why their documentation is constantly getting hammered in the press.

Don't let your engineers write manuals. Speaking of non-native English speakers. No, I'm kidding: I know plenty of engineers with good verbal skills. (Stop hitting me!) But when it comes to holding the hand of someone coming to their product anew, verbal skills aren't enough. R&D engineers are way too close to the product to be of any help to someone who doesn't know it at all. A manual writer has to be a "user advocate", who puts himself in the user's chair and says, "What do I need to know, and when?" Engineers need to be an integral part of the documentation process--they know how a product works, they know what's cool about it, they know how elegant it is--but they can't be in charge of it. They've long forgotten how someone might approach the product for the first time, and they are going to have a very hard time communicating all the cool stuff about the product to someone who hasn't gone through all that they have.

Include the documentor in the product's development process. Instead of hiring or assigning someone to write the manual when a product is finished, get that person involved in the product early. He or she can be a great help when it comes to user interface issues: if a feature cannot easily be described and its function clearly and unambiguously communicated, maybe there's something wrong with the design. The documentor should be constantly thinking about how people are going to use the product, and thus he may well have some input into features or how they are organized that the engineering and marketing people haven't thought of.

Those who design and build tools, as much as we who use them, consider that there's a lot of art in what they do. That art is about combining form, function, and utility. Do it right, and you can change the world; do it wrong, and the product gathers dust in a warehouse. Documentation is an art too, and the same elements come into play, with the same effect on success or failure. It's time that manufacturers start taking it as seriously as the rest of the development process.

Paul D. Lehrman has written manuals for companies in Japan, Germany, Korea, Massachusetts, California, and other foreign countries. He thanks Steev for the maple tree image.


These materials copyright ©1996 by Paul D. Lehrman and Intertec Publishing