Lesson Ten
Writing Instructions
Dr. Nancy Hoagland

Lecture Notes

Introduction

In this Lesson Ten, you will find information about how to write instructions more effectively. Most of us write instructions frequently, either at home or at work. I find this task one of the most difficult tasks for the technical writer because there is always the potential for misreading your audience's knowledge and abilities. Also, if you are like me, you often find yourself having to produce the instructions without adequate time to do a thorough audience analysis or to conduct a usability test. Fortunately, with experience, it is possible to improve your skills in this area. The content of this chapter should help you prepare for Assignment 5: Instructions/Technical Description/Definitions.

The last half of Marble'sChapter 20: Writing Instructions and Manuals is devoted to writing manuals. In this course, we do not consider this topic except briefly. Students are often interested in this topic and disappointed we do not study it in more depth. If you are interested in writing manuals, I suggest you read the chapter and follow the links included in TechCom Web for this topic. As you will see, much of the information on manuals is basically an extension of the first part of the chapter on writing instructions.

NOTE: Assignment 5: Instructions/Technical Description/Definitions is due on January 29 . For more information, see the Assignment Sheet for Assignment 5: Instructions/Technical Description/Definitions and the Evaluation Sheet for Assignment 5:Instructions/Technical Description/Definitions.

Chapter 20: Writing Instructions and Manuals

The goal of a set of instructions is is to enable a person to carry out a procedure safely and effectively. Instructions are effective when the user is able to perform the desired task safely without expending undue effort to locate or understand the needed information.

One of the first steps in writing instructions to do identify the audience and do a very careful analysis of that audience. The writer needs to know the general background and description of the audience, if possible. The writer also needs to know what the user already knows about the subject in order to know what content should be included. Interviewing members of the potential audience is one of the best ways to determine how much users already knows about the activity itself and about related skills, equipment, and tools. In general, the best advice is always presume that your audience knows less than you think they do.

Safety Information

Since most readers will not read the entire set of instructions before beginning, the write must make sure to included needed safety information in the beginning, long before the user has reached the step in the instructions where the safety information is needed. Safety information should then be included where relevant throughout the document. Remember that in some instances, your organization can be legally liable for instructions that fail to ensure the safety of the users.

Safety information should be written clearly and simply and identified adequately. Markel makes the point that no consistent standards exist for labeling safety information. For example, the labels "Warning" and "Caution" have different meanings in different contexts. The writer must establish a clear standard and use it consistently.

The design of safety information is an important element of writing instructions. According to Markel, safety information should "prominent and easy to read" (524). Methods of highlighting safety information include the use of upper case, larger and bolder fonts than surrounding type, the use of color, the use of symbols, and the use of textboxes. The goal is to highlight the information without creating a busy look that distracts the reader from the message.

The placement of safety information is a difficult choice because you have to second guess your readers and try to figure out how they will use the document. The best advice is to place the information as early as possible and then repeat it at the appropriate times. Markel often a word of caution that I think is good to remember. He says do not repeat the information too often--for each of 20 steps, for example--because the reader will begin to ignore the information. His solution is to repeat the safety information at the top of each page rather than have the reader begin to ignore it.

Markel includes standard from The Occupational Safety and Health Administration Guidelines for placing safety information on products and manuals. According to Markel, these standards are based on the following:

• Is the message prominently displayed so that users see it?
• Is the message large enough and clearly legible under operating conditions?
• Are the graphics and the words of the message clear and informative? (526)

Drafting Instructions

Instructions usually follow a three-part structure: an introduction, step by step information, and a conclusion.

Introduction. According to Markel, a general introduction will answer the following five questions.

• Who should carry out the task(Who is the intended reader) ?
• Why should the reader carry out the task?
• When should the reader carry out the task?
• What safety measures or other concerns should the reader understand?
• What items will the reader need?

In some instances, the answers to one of these questions is obvious or not relevant and does not need to be included. But I have discovered that providing this information up front often saves me a lot of time and trouble. I can quickly decide if an old document will be appropriate for a new audience.

Step-by-step Information. Here is a summary with comments of Markel's guidelines for writing specific steps.

• Number the various steps.
• For long instructions, use a two-level numbering system.
• If you have more than 7-10 numbered items in a sequence, many experts suggest that you divide the steps into categories or groups.
• In each step, include a single task
• Use the imperative mode for writing each step. You can memorize and use a sample phrase such as "Close the door" as the model for writing each step. Then you will be writing in the imperative mode.
• Be sure to include a feedback statement (Example: You will see a login screen.) as part of the step to which it belongs. Do not include a feedback statements as a separate step.
• Include graphics where needed.
• Do not omit little words such as articles to save space because the reader may need to words to understand the text. (528-529)

Conclusion. Instructions usually conclude with information to ensure that the reader is successful in performing the task. Some kinds conclude with a troubleshooting guide to help the reader identify and solve common problems after the task has been completed. Others tell the reader where to go for help or for additional information.

Writing Instructions for a Multicultural Audience

Markel discusses three issues related to writing for a multicultural audience (542).

Language - While translation into the reader's native language is usually the best choice, the use of simplified English is often the only alternative. The instructions should be written in a simplified, standardized vocabulary with short, uncomplicated sentences. Students in this class often make the point that the language should be accompanied by graphics that are clearly labeled.

Text or graphics - Whether in translation or in simplified English, the document should not include content or graphics that are offensive to a given audience.

Access to technology - You want to be sure that your target audience will have the capability to use the document. For example, if users have to pay minute by minute fees for Internet access, you don't want to include unnecessarily large graphics that take too long to download. (I hope students in this class who have problems with my course material will let me know. I have not had any specific complaints but I have a new version of the course up this semester with larger files. Please let me hear from you, if the design is a problem.)

NOTE: Markel points the reader to an excellent article on writing for multicultural audiences entitled "Read the F***ing Story, Then RTFM" by Michelle Delio. If you have any desire or need to write for a multicultural audience, you will enjoy this article, found on Wired News.

If you would like help in analyzing two sets of instructions including graphics and safety information, see the Interactive Sample documents for Chapter 20a and Chapter 20b from TechComm Web.

REMINDER: Assignment 4: Analytical Report is due on January 15 . For more information, see the Assignment Sheet for Assignment 4: Analytical Report and the Evaluation Sheet for Assignment 4: Analytical Report. If you want feedback on a rough draft of this assignment, you can send me a copy as an e-mail attachment before submitting it for a grade. Also, if you need an extension of the deadline, please let me know.

Under special circumstances--for example, when you are concerned about the format of the final copy, you may request permission to send me a hard copy of the report by US Mail. You must request permission prior to the due date and the hard copy must be mailed by the due date. Also, you still must post a copy in webTycho by the due date. Send the hard copy to Nancy Hoagland, 4001 West Braddock Road, Alexandria, VA 22304.

For information about writing instructions, see Module 3: Designing Documents and Creating Graphics, Instructions, and Technical Descriptions.

Material for this course was originally written and developed by Michelle Didier, Edward Harris, James Gillin, Pat Kirby, Marj Crane,Danielle Bujosa, Andrew Joyce, Ed Brandmark, Traicy Garey, and Sharon Biederman.

||  Contact Nancy Hoagland || Back to Lesson Guide  ||
||  Library Services  ||  UMUC HomePage  ||  Writing Resources  ||
||  Back toTycho Login  ||
© 1999-2000 University of Maryland University College.