Technical Writing

I'm an outspoken advocate of simple communications. (Even when I write, altho' that often takes some serious editing.)

I've spoken around the country on using simple language to sell--especially technical products such as computers.

And, User Manuals. To quote Billy Crystal, "Don't get me started." The article here will give you some idea of how I think the computer industry (as a whole) needs to communicate if we're to continue to be the essential link that hooks up EVERYONE -- to the 'net.

If you want a copy of this article e-mailed to you, click here

YOU DON'T NEED A MAP IF YOU KNOW WHERE YOU'RE GOING

By Allen Yale Harris

Users don't read software manuals. They don't read manuals and it costs you money. It costs you money because of the many tech-support phone calls that wouldn't have occurred if your users had read your manuals. Management at one software company says 50% of tech support calls were answered in the manual. Tech support answering those questions costs that company thousands of dollars each year.

Who else says users don't read manuals?

Retailers, based on their experience with requests for support, and with software returned because the user couldn't make it work.
PC consultants based on their experience.
Joe and Jane User: "I don't read software manuals because I can't find what I need." Or, "I can't understand when I read them."

Users don't read manuals and the result is lost dollars:

Lost dollars in Sales Returns and excessive tech support costs for developers and retailers.
Lost dollars in wasted time for users.
o Time wasted trying to learn the software;
o time wasted in trying to get help in learning to use it;
o time wasted in returning the software.

Probably the only people not troubled by poor manuals are PC consultants. They're happy to train users, but the meter is running.

And why don't users read your manuals? Users often complain loud and long about them. They say that few manuals are really useful for learning a new program. They say that it's hard to find what they need. Manuals are confusing, worthless for anything more than looking up what they already know.

Yet developers spend time and money to make manuals useful. Rarely, however, do they succeed. And when they fail, they fail miserably, delivering books that are abstruse, bewildering, complex and almost useless.

Obviously developers don't intend to create confusion. They spend good money on manuals. So, what's the problem? How to make user manuals readable, understandable, and useful to the end user.

The solution comes from recent experience. While rewriting a communications software manual, I tried to learn to use the program via the original user guide. I pestered the senior programmer for hours. He kept saying, "It's in the book." But the words in the book didn't make sense. Once translated, of course, they did. But they shouldn't require translation.

The point is he knew where to find the answers. But he also knew how to use the program. He didn't need a map or a user guide to tell him how to get from point A to point B. But I, his "customer," didn't know where I was going so I continually stepped in holes that the programmer never even noticed.

That's the problem. Software manuals are often written by people who already know everything about the program and never stop to consider what a beginner really needs to learn. When the manual is produced by people who know the software, it merely reminds them how to use the program. But those who most need the manual as a guide for showing them how to use the software are often disappointed. Few have the luxury of spending time with the programmer of their new software; certainly not the programmers for every program they'll ever need to learn.

The challenge we face is to create useful manuals while still meeting deadlines and adhering to budget restrictions. A software developer needs to provide the training customers need to learn their software. If a user must pay for instruction, as many do now, what affect does that have on your sales?

There's a lot to be said about improving the communications inherent in software manuals. This includes organizing, indexing meaningful subjects, providing a thorough table of contents, using straightforward layout, highlighting important concepts: names of buttons, menu items, windows, dialog boxes, via proper use of bold and underlining. But the major problem is developers write manuals perfect for power users not novices.

Your technical staff doesn't need a manual to use your software. It's quite logical, even reasonable, that they're the ones that write and edit the manual. But how can they check it for usability? Remember, they know where they are going. How can they detect miscues or misleading or inaccurate concepts? How can they really check the map?

The solution to the difficult-to-use- manuals problem lies in the writing and editing or in the testing. Ideally you'd have a writer learn the software as it is developed and write the manual as the program is learned. If the writer is competent at programming as well as a good communicator, he or she will probably have a lot to contribute throughout the development process. Certainly, this will allow time to test the manual as the software is also being tested. You test your software. Test the manual, too.

But, the simplest, and least costly solution to confusing manuals, regardless of who wrote the darn thing, is to have the manual tested by nontechnical types, or at least by techies who did not write the program. People who logically need a guide to find their way. Their problems, their stumbling blocks, as they use your draft user guide, will reveal points of confusion. Consequently, you can have your manual up to speed with the program.

The result will be happier users. Now, you'll only have to convince them that YOUR manual is worth reading.

Allen Harris, MBA, a free-lance technical writer, has taught inter-personal communications at the schools of business at USC and CSUN and has been a popular speaker at COMDEX and other computer shows on communications as it relates to effective selling. He is an accomplished sales trainer. AND has sold personal computers, and been a record setter, to prove his points - and he can be reached at 818/407-2034 or PO Box 4673, Valley Village, CA 91617-0673.