Easy as 1-2-3

By Mary Anne Donovan

Ever try to assemble a toy, bookcase, or computer and think, "I could write better instructions than these!" If yes, then read on!

You've been grappling with a new bottle of aspirin for twenty minutes and you can't get it open. Then it dawns on you -- this is a childproof cap! "Aha," you say, "adult proof, too." So, you sit down and read the instructions on the cap, which tell you to "Push down firmly and turn while pressing on tab." A little arrow shows you which direction to turn the cap. Simple enough. You follow the directions and voila, your headache's well on its way to being cured. You can thank a good technical writer for this cure to your aggravation and the cure to your headache.

Later, you're putting your child's new swing set together. It's small, two swings and a tiny teeter-totter. No problem. But when you read the instructions that come with it you wonder if you need to go to MIT first -- "Insert slot D in receptacle A to midpoint of gradient W until post R meets ring C halfway to the end of bearing 2V…" Where's that bottle of aspirin? This time you can thank a bad technical writer for your aggravation -- and your new headache.

Technical writing is an art and a science. It's an art because it takes information and conveys it to the reader in a way that enables understanding and action. It's a science because it deals with methods, systems, design, theory, and repeatable outcomes.

But Instructions are Boring

What is technical writing? Would you believe textbooks, phone books, and cookbooks? How about emails, trip reports, meeting minutes, and project reports. And, of course, there are the classics -- office procedure manuals, journal articles, and owner and user's manuals. All of these documents aim to convey information that the reader can understand and act upon.

In the last twenty years, as technology has exploded and computers have become a staple in many homes, the demand for clear, understandable and effective documentation is greater than ever. What this has meant for the field is that more woman are entering what was once a male-dominated profession, and documentation has to be written with broader audiences in mind. There are also more opportunities for freelance technical writers; with companies downsizing, many in-house technical writing departments are being disbanded and documentation is being written by freelancers.

Most important to being a good technical writer is knowing how people use text-based information and what their end goals are in using this information. And it is also not a bad idea to develop some of your own technical expertise. For example, if you want to write software documentation, then it will help you to have knowledge of a wide variety of software programs. Even if what you write about is not in your repertoire, your broad based software knowledge will be impressive to those hiring you to do a technical writing project involving software documentation.

How Do I Get Started?

The first step in a technical writing project is identifying what you need to communicate and why you need to communicate it. That's called an "objective." Always write down your "objective" in a way that keeps you focused on what information needs to be conveyed.

Now that you know what needs to be conveyed, you hone in on to whom you're going to convey it. This is called "audience analysis," but it's really a combination of common sense and proven research tools.

To write effective technical documentation, you need to know as much about your audience as possible, including education, attitude towards you, the writer, attitude towards the documentation, prior training, experience in the subject of the documentation, professional or job responsibilities, any cultural characteristics, and their intended use of the document. Don't make the mistake many technical writers make -- you are NOT the typical target reader. Undoubtedly, the person who wrote those teeter-totter instructions understood them perfectly!

How do you get this information about your readers, especially in cases where you don't have direct access to them? Technical communicators employ a variety of tools to gather information about potential readers, including interviews, surveys, questionnaires, observation, and emails or letters. In addition to your own research, clients or bosses may provide useful information.

The next step in the process is to measure the difference between your objective and your audience's skills, attitudes, knowledge, and so forth.

Example: You'll be writing the documentation for a copier targeted to home-based business owners. A telephone survey of home-based business owners in several states found that these enterprises range from highly technical (computer programming consultants) to highly untechnical (Maid services). The research also found that the copier is going to be used frequently by other members of the household including schoolchildren, and that it will be heavily relied upon an average of three hours per day, seven days a week. You know that the educational background of these particular users ranges from high school to advanced degrees. But the most important fact about this audience isn't something you need research to know, it's a matter of common sense: Time is money to these hard-working business owners. If they run into a knotty problem setting up their copier, repairing it, or dealing with technical support, they're going to think twice about doing business with the copier supplier again.

All of these audience characteristics translate into the need for you to create efficient, easy-to-read, easy-to-reference documentation that uses lots of illustrations instead of lots of words to tell the story about how to use and maintain the copier.

What About the Writing?

Phew. You've done a lot of work already and you haven't written a word! By this time you know the difference between what your reader knows/thinks/feels/does now and what she needs to know/think/feel and do as a result of reading what you write. Often, you'll need to work hand-in-hand with experts -- perhaps product engineers or designers -- to gather your content, so your ability to work collaboratively is important. In addition to gathering your information, you must also structure it so that it's clear, concise, accurate, understandable, complete, well organized, consistent, and interesting! You may even be in charge of layout and graphics. Quite a tall order, isn't it? Beyond that, as the writer of instructions, you may be just as, if not more, liable than the manufacturer should a user become injured because your instructions are deemed faulty or incorrect.

Many of the techniques used to write effective fiction or non-fiction have a place in technical writing as well. Keep these guidelines in mind as you write the documentation:

Your instructions and procedures should have clear, concise, and explicit titles. The title should answer the question "What will I be able to do using these instructions?" It should not be too broad: "Operating the Sewing Machine," or too vague, "Washing Clothes." It should describe precisely the contents and user outcome: "How to insert the bobbin into the bobbin case."

Perform the procedure or instructions yourself. Know what your reader will be up against. Make sure you can perform the procedure correctly before you sit down to write it.

Use an effective design. Whether the delivery mechanism for your instructions is electronic or print, it's your job to ensure an effective design. Think about all the design elements including use of headings, typeface, layout, graphics, and illustrations. When using illustrations, label parts and components.

Begin with a statement of context or objective for the instructions. Before launching directly into the procedure steps, tell the reader the purpose of, and objective for the instructions. Under a title of "Loading Film," you might write this purpose statement: "This procedure tells you how to load film into the camera when you are underwater."

As you write the instructions:

• Use the imperative mood: "Insert the tab into the slot." "Click on the icon." The imperative voice is direct, it puts the focus in the action the reader must perform, and it is authoritative.

• Start each step with an action verb. Like the imperative mood, beginning each step with a verb focuses on the tasks the reader must do.

• Use examples whenever you can. Examples clarify your instructions.

• Use parallel construction.

• Number the steps to eliminate any ambiguity and to ensure the procedure is performed correctly.

• Design each step so that it contains a single task. Otherwise, readers may be confused.

• Err on the side of including too much information.

How Do I Check My Instructions?

You've prepared your first draft. Now what? Let's look at those operating instructions. You think you've done a good job, but no one has actually sat down with the copier and tried your instructions to see if they really work. So, your document now needs to be validated. The most effective way to do this is to ask someone within your target audience to try and operate the equipment with only your instructions in hand. You find just such a person in your department -- the husband of a co-worker, for example. When the agreed-upon day and time arrives, you come with the copier and instructions and hand everything over to your tester. Your job now is merely to observe. Write down your observations. Record any questions the tester has. Then, incorporate that feedback into your second draft.

Should I Get The Experts' Opinions?

Once you've validated your technical document, you need to have it reviewed. People who should review your document include the engineers who gave you input, anyone the engineers ask you to send the document to, your manager(s), perhaps even a lawyer to prevent any potential liabilities, the project manager and anyone else you've worked closely with on the project. It is also helpful to ask a peer or colleague for his or her thoughts. The more the merrier -- and the more who've responded, in any way, to your document, the more assured you will be of its effectiveness and accuracy.

When you send the document out for review, include a cover sheet listing the names of all reviewers with a signature line next to each name. Insist on getting the signature of each reviewer.

Every document should be thoroughly tested to make sure it meets the users' needs. How do you test your finished documentation? Formally, use focus groups, surveys, and questionnaires. Informally, call or visit the people who use your documents and talk to them, or, ideally, watch them in action!

Hey, My Headache is Gone

Writers who create effective documentation don't win the Pulitzer Prize or the National Book Award. For the most part, they toil in anonymity. Their reward, beyond payment for the project and additional work, comes when people are able to put together shelving unit and beds, prepare meals, and figure out how to turn on the lights in their new car with a minimum of fuss. Their best work is when they're least noticed.

Mary Anne Donovan teaches technical writing and other writing courses at a small liberal arts college in Rochester, New York. She is also Chief Editor of Writer Online, an ezine dedicated to writers and lovers of writing. http://www.writeronline.us

This article originally published in Writer's Digest magazine.