COMPUTER DECISIONS

A HAYDEN PUBLICATION

Ten tips for better user manuals

by Gary Blake and Robert W. Bly

When installing the hottest new office workstation and software, the key to raising user productivity often is not the products themselves. Rather, it’s the manuals that introduce the innocent to new technology.

Poorly written manuals have plagued computer users for decades -- probably since the first electronic computer, Eniac, was switched on in 1946. A clear, easy-to-follow manual can increase productivity, save money, speed acceptance, and increase usage of a new software product or computer system. Here are 10 guidelines for your manual writers to live by. These tenets will ensure that your organization’s manuals communicate the right message to users:

1. Organize logically. The best way to organize most computer manuals is by user tasks rather than by machine functions. The distinction makes a world of difference to users. They’re much more concerned about how the product can help on their jobs than about how the system works.

For instance a word-processing manual organized by task might contain sections on “writing memos,” “writing letters,” “writing technical paper using footnotes,” “writing in script format,” “editing your work,” and “producing customized direct-mail letters.” Those headings are far more appealing and meaningful to users than section headings like “dot commands,” “cursor movement,” “block/marker identification,” “file operations,” “scroll text,” and “toggles.”

To ensure that manuals are sensibly organized, direct your writers to first make an outline. They can use the items in the outline as headings and subheadings in the final version. This procedure will help writers prepare manuals that reflect your organization’s organizational scheme, and also will break the text into short, easy-to-read sections.

2. Use numbered step-by-step instructions. Clear instructions leave no room for doubt. Use the "active" narrative voice: Start sentences with imperatives and use direct statements. For example, the manual accompanying a database package guides the reader with instructions:

Step 1. Type "UNISTOX"

Step 2. Type the report numbers you have located in Source Digest or Data Reports.

When your writers start instructions with the imperative form of a verb, the reader instantly knows what to do. Imperatives cut unnecessary verbiage, too.

3. Minimize cross-references. The overuse of cross-references makes manuals hard to follow. Here’s a real life example:

"In order for the FOCUS Report Writer (see Section 2.3.1) to read a TOTAL Database (see Database manual), the user or project designer must prepare a FOCUS Data Description (see Section 3.4.1.1 ) that is equivalent to the TOTAL Database structure (see Appendix C)."

Instead of learning the system, the user will spend most of his or her time frantically turning pages, switching from section to section for instructions or descriptions vital to understand what he or she is reading.

Cross-references are frustrating and confusing. Use only cross-references that are absolutely necessary for the user to understand the material.

Even better, provide all the information the user will need to understand a particular point in the section of the manual outlining that point in the section of the manual outlining that point. If the material to be referenced is only a sentence or two long, you’re better off repeating it wherever it's needed, rather than continually cross-referencing. If it's more than half a page, and vital to getting your meaning across, then a cross-reference is appropriate.

4. Repeat procedures until the user gets them right For example, the user has to go through the logging-on procedure regardless of which function he or she wants to perform. Should the manual repeat the procedure under every section or assume the user got it right the first time?

We recommend repeating basic procedures (loading disks, accessing programs, using menus) until you can be reasonably certain that the user is comfortable with them. When the manual writer reaches that point with the users. Procedures can be reduced to simple statements like "log onto the system" or “set margins for standard paper."

5. Show users--don’t tell them. Employees would rather do than read. Keep descriptive text to a minimum; most of the manual should give the user instructions to follow at a terminal or personal computer.

6. Use lots of illustrations. When words cannot adequately describe a thought, the manual writer should use illustration. For example, in addition to writing “Put the tape reel on the take-up drive,” present a picture of how the tape reel fits onto the drive.

7. White space and the right typeface make the manual easier to read. Readers appreciate the clear, uncluttered look of a manual that uses wide margins and lots of blank. or "white" space.

If the manual will not change, typeset the text to give it a clean professional look. Typeset text makes manuals more legible, and it also introduces an element of familiarity. It will help manuals seem like real books, as opposed to slapdash imitations of books.

If your manual will be updated frequently, you'll probably want to reproduce typed pages or printer output to save money. Three-ring binders are usually best for manuals hat are revised frequently. If a section or a page are changed, you can distribute just the changed portion, not a revision of the whole manual. But don't skimp on the "type" you present to users. Pick a typewriter or printer typeface that is easy on eyes. Daisywheel printers, for example, produce much more legible copy than dot-matrix machines. Daisywheel printers are more expensive, but the result will justify the added cost.

8. Add guideposts to aid readability. Another ploy to keep the reader on track is adding "guideposts" -- a table of contents, introduction, index, and tabs. The table of contents outlines all sections and subsections of the manual. The index should cover key terms and concepts, but not every word in the manual. If a user wonders what to do when a disk is filled to capacity, he or she should be able to find the heading, "Disk full" in the index.

9. Break the tension. Although the manual should be written in a straightforward, instructional tone, an occasional pun, joke, or other "human" interruption can break the tension and help put nervous computer novices at ease. Here's one example from one of the many guides that's been written for the IBM Personal Computer, The IBM PC Guide, by James Kelley (Banbury Books, $30):

"We need just 10 of the 255 characters in IBM’s extended set. Thus, we ought to be able to pack some 25.5 times more numeric information into a byte than is permitted by the ASCII coding scheme. That seems reasonable, doesn’t it?

"In fact, this is exactly what is done in practice. I'm not going to put a glaze in your eyes by explaining the arcane coding schemes used I'd have to look them up anyway!"

10. Test drive your manual/. Although your technical communications pros will probably review a manual writer's work, the true test of a manual's effectiveness is that it be so easy that any old user can understand it. So, give drafts of manuals to a few "typical" users for a tryout.

For instance, if a manual helps bank tellers access checking account balances, give them the manual and see if they can follow the instructions. If they have trouble, so will your organization. Better send your manual writer back to the drawing board. If the users can follow the instructions, you can be confident the manual and the new automated tool will be successful.

Gary Blake is director of The Communication Workshop, a consultancy that advises management on how to improve writing; and communication skills. Robert W. Bly is an independent copywriter specializing in high-tech advertising Blake and Bly are co-authors of Technical Writing: Structure, Standards and Style (McGraw-Hill, 1982).