6 hours

Developing Instructions

In a technical environment, you often need to learn how to perform a new activity or explain to someone how to do something. For example, you may need to describe a procedure to someone who is substituting in your position, contribute to a customer-support wiki about how to use one of your company's products, or explain how to complete an activity to a user over the telephone as a help desk representative.

Instructions are a set of commands that tell readers how to perform a task. They are a reader-oriented form of technical writing—that is, they are written from the readers' perspective. Good instructions not only tell readers how to do something but also persuade and encourage them to try a new, unfamiliar task. Clear, precise, logical instructions result in satisfied, productive readers, whereas unclear, ambiguous instructions result in frustrated readers. Instructions are found in a variety of presentation formats such as user guides, tutorials, online help, computer-based training, and multimedia presentations.

Planning Instructions

To plan your instructions, analyze the activity for which you are creating them, as well as your audience and purpose. Ask yourself:

· Who is performing the activity?

· What are they doing?

· When is it performed?

· Where is it performed?

· How is it done?

· Why is it being done?

As you plan your instructions, you become familiar with the activity and the actions and related information required to complete it. This familiarity may cause you to miss an action or to fail to describe a point as you compose your instructions. Before you begin writing instructions, think about how the activity is performed, where special information or explanation is necessary, and what the desired result is. Imagine yourself performing the activity and reflect on each step to determine what you need to tell your audience.

Analyze Your Audience for Instructions

The primary audience for instructions is usually people who are unfamiliar with an activity. They are either new to the activity or perform it infrequently. Instructions often have secondary audiences as well, such as people who are familiar with the activity and have a general idea of what to do, but who need to check a specific step or piece of important information.

When planning a set of instructions, consider your audience's needs, characteristics, and experience, all of which may be diverse. You may not be familiar with all segments of a diverse audience so as a general rule, aim your instructions at the general reader. Provide any background, definitions, explanations, and graphics a general reader would need to understand the instructions.

When your audience possesses varying levels of technical knowledge, create a design that accommodates the different groups or plan for more than one set of instructions. If your instructions will be used by an international audience, determine whether to present the instructions in several languages.

As you develop a set of instructions, consider that people who use instructions

· generally do not read them from beginning to end

· read the part of the instructions for the action they are about to perform

· skip to a specific step in the instructions when they have tried an action and are unsuccessful

· have certain expectations about what instructions should contain and how they should be presented

Identify the Purpose of Your Instructions

The primary purpose of instructions is to explain how to do something, but they can have another purpose: to persuade readers. You can encourage readers to look at the instructions beforehand, helping them to build their confidence so they can successfully complete the task. Instructions can also help project a positive image of an organization's products and services.

Organizing Instructions

Instructions are generally organized chronologically, telling readers how to complete a task through a series of steps. In your introduction, provide an overview of the instructions and present information that relates to the entire activity. The introduction can include the purpose; the intended reader; any assumptions, definitions, necessary materials, and equipment; and an advance organizer.

In the body of the instructions, present the detailed steps including the action, any results of the action, safety information, and other explanations or definitions. If a conclusion is needed, you can wrap up the instructions by summarizing the major steps, referring readers to other information, or describing what to do if a problem occurs.

Task-Oriented Writing Strategies for Instructions

Using task-oriented writing strategies, such as active voice, imperative mood, present tense, precise language, and positive terminology, helps you achieve good reader-oriented instructions. Using the active voice in instructions helps engage readers, making them feel involved in the action. In Table 3.4, we describe these strategies and offer examples.

Table 3.4 Task-Oriented Writing Strategies

Writing Strategy	Description	Example(s)
Imperative mood	· Focuses readers on the action. · Putting the action verb at the beginning of a command in the imperative mood emphasizes the action, reinforcing what the reader should do. · Using the imperative mood with active voice conveys directly and clearly to readers what actions they should take.	Look at the following examples to see the difference: · Pour the water on the soil covering the seeds until the soil is wet but not saturated. · The water is poured on the soil covering the seeds until the soil is wet but not saturated. · You should pour water on the soil that covers the seeds until the soil is wet but not saturated.
Present tense	· Helps readers get involved in the action, especially when describing the results of an action · Creates the sense of the action happening as the audience reads the instructions	Compare the two ways to phrase the response to the action of clicking a button on a computer screen to update a record: Command: Press the Save button to update the record to the Portfolio database. Response 1: The system will add the record to the database. Response 2: The system adds the record to the database.
Precise, concrete word choice and phrasing	· Communicates clearly to readers what to do and how · Promotes readers' confidence because they understand what to do · Improves readers' comprehension · Note: Be aware of the details your readers need and try not to assume that they know them.	Suppose the owner of a new computer sees this step in the computer start-up procedure: Turn on the computer. Rephrase the step to make it more precise such as, Press the button labeled On/Off on the front panel of the machine to turn on the computer.
Positive terminology	· Encourages readers to respond favorably to instructions. · Avoids use of instructions containing a qualifying negative such as except. · Note: In some situations, you can use negative phrasing effectively, especially in warnings or cautions. For example, this warning, Do NOT use your cellular phone in the shower, gets readers' attention quicker than a positively phrased warning would.	Example 1: Choose all except three items. Rephrase positively as: Choose five items. Example 2: A note in the coffee grinder instructions states, "Do not wash the ground coffee container in an automatic dishwasher." Rephrase this note more positively as follows: "Always wash the ground coffee container by hand."

Arranging Information in Instructions

Effective instructions are organized clearly and logically so that readers can find information quickly and easily, especially when they perform the actions as they read. Good organization also enables diverse audiences to find the specific information when they need it. For instance, included in the instructions for using a coffee grinder are the following steps (The Waring Coffee Grinder Instructions, n.d.):

3. Place coffee beans in the cylindrical storage hopper on the top of the unit…

4. Place cover on bean storage hopper.

5. Set ground coffee container with cover assembled, in position. Be sure that it snaps securely in place…

9. When preparing to grind coffee beans, be sure the intake sealing plug is removed and the ground coffee container is properly in place in the unit. Failure to do so will allow ground coffee to escape.

These instructions can be improved. Notice that step 9, the instructions about removing the sealing plug, should be presented earlier in the instructions, after step 4, and should emphasize the information more prominently, like this:

3. Place coffee beans in the cylindrical storage hopper on the top of the unit…

4. Place cover on bean storage hopper.

Note: When preparing to grind coffee beans, be sure the intake sealing plug is removed and the ground coffee container is properly in place in the unit. Failure to do so will allow ground coffee to escape.

5. Set ground coffee container with cover assembled, in position. Be sure that it snaps securely in place…

As you can see from the example, sequencing steps logically and providing critical information at the correct place makes instructions more useful and effective.

Besides sequencing steps, other strategies for effectively organizing instructions are chunking information; clearly delineating steps; using lists; writing short, simple sentences; maintaining parallel structure; supplying transitions; and layering.

Chunking breaks actions down into small units that readers can more easily comprehend and perform. Chunking, along with conveying each action in a separately numbered step, facilitates readers' ability to absorb and retain information.

Look at the following instructions to set the time on an alarm clock (University of Maryland University College, 1997, pp. 10–12):

TO SET THE TIME:

Plug in the alarm clock. The display will flash. Depress and hold the TIME button. At the same time depress and hold the HOUR button until you reach the correct hour and then release only the HOUR button. Continue to hold the TIME button and depress and hold the MINUTE button until you reach the correct minute and then release both the TIME and MINUTE buttons. You have now set the time. NOTE: AM/PM will appear in the lower left-hand corner of the display. Be sure to set the time for the correct 12-hour period—A.M. (morning) or P.M. (evening).

This paragraph contains multiple actions and results in a block of text that is not easy to read and decipher. Finding a specific step is difficult. You can break this information down into a series of steps that makes the information easier to find. The steps are based on the actions—turning on the clock, setting the hour, and setting the minutes—necessary to set the clock.

Besides helping you to chunk information, lists also highlight each step, enabling readers to find information more easily. A list can help readers locate their place in instructions, especially when they are reading a step, doing an action, and then returning to the instructions to read another step.

When chunking information, use short, simple sentences, each of which is focused on one idea. Try to present familiar or important information, such as reasons or special conditions necessary for doing the step, at the beginning of each sentence. Doing so helps readers to understand why they are completing the action. For example, look at this step from instructions for changing a toner cartridge:

Shake the toner cartridge before inserting it in the printer to enable consistent printing.

You can rephrase the sentence to begin with information about the reason readers must shake the cartridge:

To improve printing consistency, shake the toner cartridge before inserting it in the printer.

Maintaining a consistent organizational structure throughout a set of instructions helps readers follow the steps and find information. In each list, set of steps, or set of headings, use a parallel grammatical structure to establish a consistent, repeating format that becomes familiar to readers and enhances their retrieval and use of the information. Parallelism reinforces the step-by-step structure of instructions. For instance, see how the inconsistent structure of the following two commands breaks the pattern of the instructions:

1. Oil should be poured in the skillet. 2. Spread oil evenly in the skillet.

You can change the first step, to achieve parallel structure, like this:

1. Pour oil in the skillet.

Using transition words is a writing strategy for indicating a sequence or time and connecting related ideas. Note the transition words first, next, and finally in this example:

When planning a hiking trip, first decide on a location and the route to follow as you hike. Next, look at maps to determine the best route. Finally, fill out a hiking plan form, which lists important information about the members of your hiking party and your itinerary.

When creating instructions for diverse audiences, the technique of layering enables you to present information at different levels of detail or to present different types of information. You layer each level of information with the amount and type of information appropriate for that audience. In printed documents, you can layer information by using a system of headings or lists, and in online documents, you can insert links and popups. Layering is frequently used in instructions in online documents. Review Clear Cache in the Defining Technical Terms section of module 1 to see an example of layering.

Using Graphics in Instructions

Graphics serve numerous purposes in instructions, including

· showing the parts, equipment, or materials needed for completing a task

· showing how a piece of equipment is assembled or how one piece relates to another

· directing people to different types of information

· identifying different types of information

· illustrating the results of an action

Graphics are especially beneficial in instructions directed to an international audience. In fact, these instructions may be completely graphical. For instance, instructions designed to explain safety and evacuation procedures on airlines are often completely graphical.

Tables are useful in condensing information and clearly denoting or specifying options. One type of table, an if/then or decision table, is an effective means for presenting options to readers in a clear, easy-to-follow format. For example, to direct readers to different parts of a user manual, you could use an if/then table like this:

If you want to:	Go to this section:
Add a user record	Entering records
Change an existing user record	Changing records
Delete a user record	Deleting records

Notes, Cautions, and Warnings in Instructions

Instructions help ensure safety and reliability by alerting readers to critical information about the dangers of using products or services. Safety information should be easy to read so readers can grasp it quickly. Display this information prominently and at the appropriate point in the instructions when readers need it, immediately before the action, not after it has occurred.

Safety information includes notes, cautions, warnings, and danger alerts. The American National Standards Institute (ANSI) publishes Standard Z535.4, which identifies these four levels with signal words (Note, Caution, Warning, and Danger), a symbol, and color. See your textbook for more information about safety information.

Review this example of well-written instructions. Roll your mouse over the numbers to read more explanation.

Testing Instructions

As you develop instructions, you should test them for completeness, accuracy, and understandability. Testing instructions during their development can identify what is useful and beneficial as well as what needs improvement. Testing helps to ensure a high-quality product.

Usability testing is the process of conducting experiments with people who use the instructions to see how easily and accurately they can complete the task and how well the instructions work. The goals of this testing include developing safe and accurate products and services, increasing customer satisfaction, and reducing customer-support costs.

Instructions should be tested during the product development process. In the design and development phase, ask people who work with the product to test your draft instructions and provide feedback. When your instructions are in final draft form, test them again to see how well they meet their purpose and how easy they are to use and follow.

After conducting the test, analyze your findings. Identify evaluation criteria to help you. You can base your criteria on the instructions' intended use, user characteristics, and environmental factors. Criteria for evaluating the usability of instructions include:

· accuracy

· ease of understanding and following

· logical arrangement, with one action per step

· clear organization so that pieces of information can be found efficiently

Developing Technical Descriptions

Technical descriptions explain how equipment, machines, or objects operate and are assembled and what happens during a process. A process can include an event, such as a hurricane, or an activity, such as the transmission of an e-mail message. Technical descriptions of these objects and processes help readers understand what they do, how they function, when and where they happen, and why. They can also help readers understand a topic, especially an abstract topic.

Technical Descriptions of Objects

When working with appliances, equipment, or other objects, we frequently need a description to understand their assembly and components. An object description helps readers grasp the physical structure and assembly of an item, enabling them to develop a mental image of the object and how its components relate to each other.

Object descriptions are useful in a variety of situations to enable the audience to better understand what the object looks like and how it functions, for example:

· To prepare to install a ceiling fan, a homeowner reads a description of an electrical switch to see how wires are connected and to learn more about the switch.

· To determine how to clear a paper jam from a laser printer, users refer to the user guide's description and diagram of the printer.

· To evaluate the options for upgrading a local area network (LAN), a telecommunications specialist reviews the various configuration alternatives and diagrams presented in a report analyzing a LAN upgrade.

Technical Descriptions of Processes

In a process explanation, you explain chronologically how a process occurs from a logical beginning point to a logical ending point, giving readers a sense of the actions that occur during the process. This explanation gives an overview to readers who need to know what happens in a process, but do not need to do it themselves. The focus is on what happens and why the process occurs, not how it happens. Process descriptions are helpful in situations such as explaining

· department activities to supervisors who need to know about them, but do not generally perform them

· a new process to technicians or operators who must understand what is happening and why before attempting to read the instructions to do it

· what occurs during a natural process or event, such as a hurricane or blood flow through the body, to help readers increase their knowledge and understanding

A process explanation differs from instructions in its focus and purpose. It describes a process, whereas instructions present a series of commands and supporting information about how to do something.

Process explanations can vary from a graphic with a few words to a long document. A graphic can provide a simple overview of the process, such as how nitrogen cycles between the air and the Earth.

Where to Locate Technical Descriptions

Technical descriptions are often combined with other types of technical writing in documents. You can include a description of an object before a set of instructions so that readers understand how the object works before using it. For example, suppose you are preparing instructions for operating a dishwasher. First you may explain briefly the different buttons, their purpose, and their arrangement on the dishwasher panel. A process explanation may be incorporated into a report or a proposal. For example, in a proposal to reorganize your department's staff, you can describe the process that will be used to develop a reorganization plan.

Analyzing the Audience for Technical Descriptions

The readers of a technical description are generally unfamiliar with the topic or encounter it infrequently and need more information about it. The audience needs a clear, logically organized description to understand how an object is assembled, how its parts function, or what happens in a process.

As you plan your description, ask yourself these questions about your audience:

· Why do they need this information?

· What do they already know about the process or object?

· Do they have previous experience related to this process or object?

· What will they do with this information?

· What information about the process must be emphasized for them?

Identifying the Purpose of Technical Descriptions

The purpose of a technical description influences how you should organize it and what you include. A technical description can:

· increase readers' knowledge of a process or object to help them understand what happens or how it is assembled, to satisfy their curiosity, or to see how it affects their work

· communicate activities and developments in a discipline to other professionals

· provide information to be used in making a decision or taking action

The purpose will help you select the information to impart as well as the method of dividing the information for the description.

Organizing Technical Descriptions

Organize technical descriptions according to the breakdown of the object or process. You can organize your object description using one of three patterns: spatial, chronological, or priority. Always organize a process explanation chronologically.

When describing an object, focus in the introduction on the whole object and its characteristics, such as dimensions, shape, color, and texture. Towards the end of your introduction, identify the way you will break down the object in the body of your description. This breakdown description is an advance organizer similar to the examples shown in the reports tutorial in module 2. In a conclusion, describe how the components fit and work together.

In the introduction to a process explanation, define the process and its purpose, provide necessary background information, and describe when and where it happens and any special considerations. Towards the end of your introduction, identify the sequence of stages in the process using an advance organizer. Then, in the body, expand sequentially your description of each stage. Indicate any relationships between the stages.

Use transitions as you move from one part of the description to another to guide readers and improve the flow. Additionally, maintain a parallel structure throughout your description.

Characteristics of Technical Descriptions

The characteristics of a technical description help readers develop a mental image of an object or an understanding of the flow of a process. Language (for example, use of active or passive voice or first, second, or third person), partitioning, and graphics can help you create this image. We will describe these characteristics in the following sections.

Language in Technical Descriptions

The language used in technical descriptions should be clear and precise. When describing an object, choose concrete, specific, accurate words or phrases that communicate the attributes of the object—its size, shape, colors, texture, and position. For example, words such as gritty, rough, scaly, U-shaped, and elliptical convey distinct images to readers.

A technical description concentrates on the object or process. When the object or process rather than the writer is the focus, use the third-person perspective. This perspective is most commonly used in process explanations.

The decision whether to use active voice or passive voice should be based on the topic, focus, purpose, and audience of the technical description. Active voice is preferred when the focus is on the subject of the action rather than the object or result of the action. Passive voice is appropriate when the result of the action is important or when the actor is unimportant.

For example, suppose you are explaining the process of assigning project numbers to new projects in your office. If the accountants, who perform this action, are the focus of your explanation, use the active voice to emphasize the accountant, the doer of the action. On the other hand, if your focus is the project tracking number (PTN), the object or recipient of the action, use the passive voice to focus attention on the PTN.

Description Using Active Voice

Description Using Passive Voice

The accountants assign the project tracking number (PTN). They derive a unique six-digit number for each project that identifies the responsible division, status, department, and type of project. They enter the PTN in their database and record the number on the project tracking form. After the accountants assign the PTN and complete the tracking form, they distribute them to the systems administrator, project tracking office, and contracts office.

The project tracking number (PTN) is assigned by the accountants. This unique, six-digit number identifies the responsible division, status, department, and type of project. The PTN is created by the accountants, entered in the accounting database, and recorded on the project tracking form. The completed form is then distributed by the accountants to the systems administrator, project tracking office, and contracts office.

Partitioning in Technical Descriptions

Effective partitioning is important in a technical description. Similar to chunking, partitioning means breaking down an object into its components or a process into smaller, related steps or stages. Partitioning can help readers understand how the object is constructed and operates or what happens during each step of a process.

An object consists of different parts that work together to achieve its function. For example, a screw is an object and can be described thus:

A screw consists of two parts: stem and head. The stem is circular and has threads embedded in its surface for driving it into another substance. The head is raised, has a greater diameter than the stem, is often circular, and is slotted so a tool can drive the stem into another surface. You insert a tool, such as a screwdriver, into the slot in the head to drive the stem into a substance, such as wood.

The separation of a screw into its parts is an example of partitioning.

Sometimes you can partition an object by structural parts or functional parts. When dividing by structural parts, separate the parts according to their physical appearance, not their function. For example, if you describe the external parts of a personal computer (PC), you would likely partition it by its physical parts. When dividing by functional parts, you separate parts based on how they work during the operation of the object. The description of the screw is based on its separation by functional parts.

Partitioning a process into a series of stages helps readers comprehend the stages and assimilate them into the whole process. They can see how the stages relate to each other and how the activities in one stage can affect another stage of the process. Identifying stages helps you define how the process flows and plan how to explain it to your audience. As you break the process down, identify logically related chunks of information that constitute a unit. For example, the process of preparing a report can be separated into the following stages:

1. define the issue or problem and the purpose of the report

2. identify the audience and their needs

3. develop a research plan and conduct the research

4. interpret the information that has been gathered

5. evaluate, refine, and revise ideas and thoughts as the analysis evolves

6. organize these ideas and thoughts

7. draw conclusions

8. make recommendations

You can further subdivide each of these stages into a series of steps. For example, you can decompose stage 3, develop a research plan and conduct the research, into a series of steps, identifying separate activities for developing your research plan and conducting your research. Your steps for this stage might include the following:

3. develop a research plan and conduct the research

· develop initial research plan

· develop initial research schedule

· revise research plan and schedule

· develop a preliminary outline

· prepare, pretest, and conduct survey

· conduct interviews

· search relevant literature

When you explain a complex process, partitioning it at several levels helps to present the information to readers in small chunks.

Using Graphics in Technical Descriptions

Graphics are used in technical descriptions to illustrate how the parts of an object fit together or the steps of a process occur, to summarize the flow of a process, and to explain abstract concepts. Graphics are especially beneficial for visually oriented or multicultural readers.

Several types of graphics are effective in process explanations. Graphics that depict the process with its sequence of stages include flowcharts, time lines, and schedules. Graphics that show an object and its parts include photographs, exploded diagrams, and cutaway view diagrams.

Here is an example of a well-written technical description.

References

Adobe Systems. (2009). Adobe and PDF. Retrieved January 24, 2009, from http://www.adobe.com/products/acrobat/adobepdf.html

Chaparro, B., Baker, J., Shaikh, A., Hull, S., & Brady, L. (2004, July). Reading online text: A comparison of four white space layouts. Usability News. Retrieved March 13, 2009, from http://www.surl.org/usabilitynews/62/pdf/Usability%20News%2062%20-%20Chaparro.pdf

Craig, J., Scala, I., & Bevington, W. (2006). Designing with type: The essential guide to typography (5th ed). New York: Watson-Guptill.

Darby, P. (2008). Technical description of a stapler. Unpuplished paper, University of Maryland University College, College Park, MD.

Deemer, D. (2008). Technical description of a stapler. Unpublished paper, University of Maryland University College, College Park, MD. 

Dobrin, S., Keller, C., & Weisser, C. (2008). Technical communication in the twenty-first century. Upper Saddle River, NJ: Pearson Prentice Hall.

Haley, A. (2009). Typefaces for the Web. Retrieved January 24, 2009, from http://www.fonts.com/AboutFonts/Articles/Typography/TypefacesForWeb.htm

Lannon, J. (2008). Technical communication (11th ed.). New York: Pearson Longman.

MacGregor, C. (2001, September 26). Are you designing for your eyes only? Retrieved February 24, 2009, from http://www.flazoom.com/news/legibility_09252001.shtml

Matis, D. (1996). The graphic design of text. Intercom. 43(2), 22–23.

Morkes, N.. & Nielsen, J. (1997). Concise, scannable, and objective: How to write for the Web. Retrieved January 22, 2009, from http://www.useit.com/papers/webwriting/writing.html

Niederst, J. (2006). Web design in a nutshell (2nd ed). Cambridge: O'Reilly.

Nielsen, J. (1997, October 1 ). How users read on the Web. Retrieved January 22, 2009, from http://www.useit.com/alertbox/9710a.html

Piazza, W. (2008). Technical communication in the twenty-first century. Upper Saddle River, NJ: Pearson Prentice Hall.  

Robbins, J. (2007). Learning Web design: A beginner's guide to (X)HTML, style sheets and Web graphics (3rd ed). Cambridge: O'Reilly.

Sevilla, C. (June 2002). Page design: Directing the reader's eye [Electronic version]. Intercom, 6–9.

The Waring coffee grinder instructions. (n.d.). New Hartford, CT: Waring.

University of Maryland University College. (1997). Technical writing course guide. College Park, MD: UMUC

Web Design Group. (2006). Image use on the Web. Retrieved February 23, 2009, from http://htmlhelp.com/design/imageuse.htm

Webopedia. (2009). Graphics file formats: A quick reference. Retrieved January 24, 2009, from http://www.webopedia.com/quick_ref/graphics_formats.asp

World Wide Web Consortium. (2008). Web accessibility quicktips: WCAG 2 at a glance. Retrieved February 22, 2009, from http://www.w3.org/WAI/WCAG20/glance/

Report broken links or any other problems on this page. Copyright © by University of Maryland University College.