11: Instructions

Chapter Objectives

• Identify the three types of instructions.
• Explain the main components of instructions.
• Exemplify an effective set of instructions.

An important part of technical and report writing is the use of definitions, descriptions, and instructions. They often work together to clarify the purpose and information in a technical document for an audience. This series of three chapters look at these three elements: definitions, descriptions, and instructions, more closely, so that you understand how to incorporate them into your technical documents to achieve clarity and conciseness. For that reason, you will find this introduction at the beginning of each chapter to remind you of their interconnectedness.

Definitions

We grow up reading these from the time we are in elementary school. They are one of the more common patterns of organization used. Definitions can be simple short insertions in a sentence to clarify a term, or they can be an entire document known as an extended definition.

Descriptions

These are similar to a definition but can be longer, more detailed, and have a visual representation to further explain a concept. More than likely, you have read these as well. Descriptions explain objects, mechanisms, and processes – and they do so in a way that whatever is being described is easily understood. If a description of the greenhouse effect was created for specialists in the field, it might be more complex. If this same idea was written for a general audience, the language would be simplified.

Instructions

Instructions provide step-by-step explanations of how to do things: assemble something, operate something, repair something, or explain a personal process (enrolling in college, for example) so that readers may better understand it and possibly use it themselves.

What are Instructions?

Process texts are common in school and professions. In school, instructors frequently assign process assignments. For example, humanities professors may ask for a description of how an artistic or literary period evolved; history professors might ask for the contributions of a culture’s leaders over time; social science professors - the chronology of inventions; engineering professors will ask for explanations of how sound is changed into electrical signals, and business professors might want an explanation of how the Federal Reserve works or how to sell a product.

On a daily basis, we read descriptive processes, including recipes, user manuals for new software, or advice columns on how to lose weight or how to succeed in school or a profession. These texts focus on answering one of the following questions:

• “How is this done?”
• “How can I do this?”

While the topics of a process report or a set of instructions may vary, they share several similarities:

1. They are written to explain how something works
2. They are structured in chronological order using numbered steps
3. Most include visuals. In writing instructions for learning a new software program, for example, writers might use screenshots and/or screen videos to walk users through the tutorial.

Types of Instructions

There are three main types of process texts:

• Descriptive processes: these answer the question, “How is this done?” These texts describe how a process occurs so that readers can understand it better. For example, writing a descriptive process about how you registered for a course online rather than in person might be useful to someone who has never done online registration.
  
• Prescriptive processes: these are explanatory in nature; they prescribe how something is done (or should be done) so that readers can do it themselves. These are the most common type of instructional documents. For example, you might write a prescriptive process guide for users explaining how to perform basic maintenance on their cars, such as changing their own oil, checking spark plugs, or replacing brake pads. *The samples listed below are examples of prescriptive processes.
  
• Blended descriptive and prescriptive processes make the main thrust of the document a descriptive process while having a few sections summarizing how the readers can perform the process. In other words, writers may address both “How can I do this?” and “How is this done?” in different parts of one text. Alternatively, they might develop different versions of the same document for two audiences–an audience of users and an audience of interested parties.

Content of Instructions

Be sure to read the chapter on Visuals in Technical Documents before creating your instructions. Generally speaking, writers of instructions should strive to do the following:

• Use clear, simple writing whenever possible.
• Have a thorough understanding of the process in all its technical detail.
• Put yourself in the place of your audience who will be using your instructions.
• Use direct address, active voice, and imperative mood. Write instructions in the second person as direct address to emphasize the role of the audience. Begin all steps with action verbs. For example, "Place the panel on the floor," instead of "The panel should be placed on the floor" or "You should place the panel on the floor."
  

Instructions should include the following items:

Introduction: In carefully planning your instructions’ introduction, be sure to:

• Indicate the specific task or procedure to be explained.
• Indicate what the audience needs in terms of knowledge and background to understand the instructions.
• Give a general idea of the procedure and what it accomplishes.
• Indicate the conditions when these instructions should (or should not) be used.
• Give an overview of the contents of the instructions.

Headings: Headings help orient the user by organizing information, helping the reader understand what is contained in each section, and allowing them to quickly find information.

General warning, caution, danger notices: Instructions must also alert readers to the possibility of ruining their equipment, screwing up the procedure, and/or hurting themselves. Also, instructions must emphasize key points or exceptions. For these situations, you should use special notices, such as Note, Warning, Caution, and/or Danger (see Chapter on Document Design Basics for detailed instructions.)

Technical background or theory: At the beginning of some instructions (usually after the introduction), you may need a discussion of background related to the procedure. For certain instructions, this background is critical—otherwise, the steps in the procedure make no sense. In some cases, writers of instructions may need to spend significant time explaining things to readers before moving on to the actual steps involved in the process.

Equipment and supplies: Most instructions include a list of the things you need to gather before you start the procedure. This includes equipment, the tools you use in the procedure (such as mixing bowls, spoons, bread pans, hammers, drills, and saws) and supplies, the things that are consumed in the procedure (such as wood, paint, oil, flour, and nails). In instructions, these are typically listed either in a simple vertical list or in a two-column list at the start of the instructions. Use the two-column list if you need to add specifications to some or all of the items—for example, brand names, sizes, amounts, types, model numbers, and so on.

General warning, caution, danger notices: Instructions must also alert readers to the possibility of ruining their equipment, screwing up the procedure, and/or hurting themselves. Also, instructions must emphasize key points or exceptions. For these situations, you should use special notices, such as Note, Warning, Caution, and/or Danger (see Chapter on Document Design Basics for detailed instructions.)

Order of steps: When you get to the actual writing of the steps be certain to carefully consider the structure and format of those steps, and any supplementary information that might be needed. The steps should be listed in chronological order with warnings, cautions, and troubleshooting included where needed.

Visuals: Good instructions have both text and visuals since your audience is likely comprised of people with different learning styles. However, the use of visuals can vary depending on your audience and the intended use of the instructions. Visuals help to clarify a concept that is difficult to explain using only words. Graphics may be used to show how something looks, how something should look once the step has been completed, how something is done or constructed, show trends or relationships, or help to organize information. Graphics are useful since almost everyone (including children and others of a different language) can understand visual instructions and see exactly what they need to complete. (See Chapter 15 Visuals in Technical Documents.)

Note: While visuals are useful, accessible instructions do not rely solely on visuals and instead, include text that repeats the information given in the visuals.

Audience and Characteristics

At the beginning of an instruction-writing project, it is important to consider your audience and determine the characteristics (the number of tasks and steps) of the particular procedure you intend to write about.

Audience: Early in the process, define the audience and situation of your instructions. Remember that defining an audience means defining its level of knowledge and familiarity with the topic. It is helpful to describe your audience to yourself first, and then use that to assess your message to ensure it is appropriate for your audience.

Characteristics: An important consideration is how many tasks there are in the procedure for which you are writing instructions. The term procedure can be used to refer to the complete set of activities your instructions discuss, while the task can be used to define a semi-independent group of actions within the procedure.

Understand Task vs Procedure

Setting up your modem is one task in the overall procedure of connecting a computer to the internet. Whereas a simple procedure like changing a car’s oil contains only one task; there are no semi-independent groupings of other activities.

A more complex procedure, like using a microwave oven, contains plenty of semi-independent tasks, such as setting the clock, setting the power level, using the timer, cleaning and maintaining the microwave, and more.

Use Phases to organize: Some instructions have only a single task but have many steps within that single task. For example, imagine the multiple tasks required to assemble a children’s swing set. One effective approach would be to group similar and related steps into phases, and then renumber the steps at each new phase. A phase is a group of similar steps within a single-task procedure. In the swing set example, setting up the frame would be one phase; anchoring the thing in the ground would be another, and assembling the box swing would be still another. The "How to Operate the Minolta Freedom 3 Camera" instructions below (Example Instructions) uses phases for each set of tasks.

Identifying Tasks

When you write instructions, procedures, or user-guide information, you must use a task approach. That means providing steps and explanations for all the major tasks that users may need to perform. Of course, some instructions involve only one task—for example, changing the oil in a car. But we are concerned here with more complex procedures. While this chapter uses computer software as an example, these techniques can apply to any multi-task procedure—for example, operating a microwave oven.

To write in a task-oriented manner, you first have to do some task analysis. That means studying how users use the product or do the task, interviewing them, and watching them. It can also mean interviewing marketing and product developers. If you can get your hands on the kinds of questions that help-desk people receive, that helps too.

But sometimes, you may not be in a position to do a thorough task analysis. Typically, product developers don't think about documentation until rather late. In these circumstances, it's often difficult to get marketing, development, engineering, and programming people to spend enough time with you to explain the product thoroughly. And so you end up doing a certain amount of educated guesswork. The developer is more likely to review your draft and let you know if your guesswork is right.

Example: Conducting a Task Analysis

To develop a task analysis, you can study the user interface (buttons, menus, options, etc.) of the product. This goes for both hardware and software. Consider the interface for the icon editing tool shown to the right: From just this snippet of the interface, you can identify several obvious tasks: Start a new icon project Open an existing icon project for editing Rename an icon project (Save As) Exit AZ Icon Edit Check out the Usability.gov website for a full explanation of "user interface."

Interface for AZ Icon Edit

Now, look at the menu options for the next parts of the menu. You can see that when people are using this icon editor, they'll also most likely be doing these tasks: Undo a mistake Capture an image or some part of it Cut something out of an icon project Copy something out of an icon project Paste something into an icon project Flip the entire image horizontally or vertically Rotate the image left Clear the project, which probably means start over Restore, which you'll have to ask around, experiment with, or dig into the programming spec to find out about Draw with a thick, medium, or thin line.

But now look at the interface without the menu options hanging down. What additional tasks can you see? As with a lot of graphical user interfaces, some of the icons duplicate the menu options. For example, the bulleted-list icon enables you to select a thin, medium, or thick line the same way clicking on Options does. However, there are some new tools here, not available elsewhere in the interface: Draw straight lines (you'll have to experiment to see the difference between the two pencil icons) Draw freehand lines (the wavy-line icon) Draw unfilled rectangles (sharp edges) and unfilled rectangles (rounded edges) Draw unfilled ovals and filled ovals Fill with color (the hypodermic needle) Select portions of the image to move, cut, or rotate (the dotted-line icon) Capture images—or parts of images— (the net, but how does it work?) Draw filled rectangles (sharp edges) and filled rectangles (rounded edges) Select background color (the Screen button) Select line or fill color (the double-box icon)

There's a lot you still don't know about this software, but you've already done a lot of guesswork toward defining the major tasks. You would want to group and consolidate things into phases, perhaps like the following:

• Creating, editing, renaming, and saving icons
• Selecting foreground and background color
• Drawing lines, rectangles, and ovals
• Cutting, pasting, and copying objects
• Moving, flipping, and rotating objects

You can see that in this rough task list, there is no trace of tasks such as filling an object with color, capturing images, clearing the workspace, undoing a mistake, or restoring. But as you work, these details will begin to find their place in your scheme. Now, stand back from the details of the interface and put yourself in the place of an icon software user. What questions is that individual likely to ask? "How do I change the color of the background?" We've got that covered. "How do I change the thickness of the lines I draw?" Got that one covered too. "How do I make the background transparent?" Hmmm . . . that will be an issue for the color section, but it will take some research.

Formatting Numbers

Technical writing breaks some of those rules you worked so hard to learn in past writing classes. In the technical writing context, we are often vitally concerned about numbers and want them to stand out. (For number formatting rules, see Chapter 15 Visuals in Technical Documents).

Rule: You should use numerals in running text when the number indicates an exact, measured or measurable amount, or when it represents a critical value.

Example: Numbers in Instructions

In the following sentences, it matters that the numbers are exact:

The cup is 3 inches in diameter.

Use 4 tacks to fasten the poster to the wall.

However, this does not mean using numerals for indifferent values. For example, in this sentence, there is nothing heart-stopping about how many sections the report has:

The report contains four major sections.

See the section on "Numbers vs. Words" and "Symbols" in APA resources for further details.

Designing Instructions

• Provide a title that clearly tells your audience what to expect. For example, "Instructions for Using XYZ Design Software" is clear and limiting. Your audience knows what the document will include (How to use the software) and what it won't include (How to design a brochure).
• Provide an introduction for your audience that states the purpose of the instructions. For example, "These instructions will guide you through each step of using XYZ Design Software" to create a variety of documents."
• Use headings that tell the reader what to expect and emphasizes what is most important. A heading that states "Drawing Rectangles and Ovals" is more informative than "Rectangles and Ovals."
• Use bold, italics, and font size to highlight or emphasize headings, or other important information. Use these elements consistently throughout the document. For example, if you use underlining for emphasis in a step, be sure you use underlining each time you emphasize something in a step. If you use bold for a parts name, be sure to use bold for every parts name.
• Use an easy-to-read font style. Use standard fonts such as Arial or Times New Roman. Do not use more than two font families throughout the document, and use them consistently. For example, if you use Arial for headings and Times New Roman for the text, use that same format throughout the document.
• Provide a list of parts, when necessary. Label each part and use that same identification in your instructions. For example, don't label the part "Icon" and then use the term "Picture" in your instructions.
• Use visuals to illustrate steps that are complicated. You can use software to draw the image or use photographs of completed step to show your audience how the completed task looks.
• Arrange the steps in a numbered list to help readers keep track of their progress. Include only one step per sentence. Use sub-steps for instructions that are divided by phases or where steps are more complicated (For list formatting rules, see Chapter 15 Visuals in Technical Documents.)
• Include the appropriate level of detail and technicality. Consider your instructions from the perspective of a non-technical audience and give the necessary details to explain what to do. For example, instead of "Open the dropdown list for the image," explain how your audience should complete that task: "Using the mouse, move the cursor over the image and right-click on the mouse to open the dropdown list."
• Explain the purpose of the instruction by providing background information. For example, "You should open the dropdown list for each image to see all the editing options that are available," or "Save your document often throughout the design process to prevent the loss of your work."
• Leave white space between steps to separate the steps visually.
• Keep the steps close to the visual information. Use the same placement for each written step and visual so your audience knows where to find each step. Do not vary the placement of steps and visuals. (i.e., All steps are above each visual, or all steps are alongside each visual, etc.)
• Visual and verbal information must be redundant. The visual should restate or reinforce the verbal information, not replace it.
• Provide warnings, cautions, or troubleshooting advice. To protect the safety of the user and the liability of your company, you must anticipate those tasks where the user could injure themselves or damage the product, and provide suitable warnings. If the step is tricky, be sure to include troubleshooting advice to help the user figure out how to resolve a problem.

Evaluating the Usability of Instructions

To ensure your instructions meet the needs of your audience, you must conduct a usability study of your completed document. In a usable document, the audience can easily find the information they need, understand the information, and use it to safely and effectively complete the task. Remember, the end goal for any document is that the audience is able to use it; nowhere is this more important than in instructions and procedures where safety and liability concerns can cost lives and money.

Conducting a usability test can help you find the areas where steps are unclear or there is missing information. Put yourself in the position of your audience when you conduct the usability test. If possible, ask someone else to use your instructions and have them make notes on the areas they thought were unclear or confusing.

• GENERAL INSTRUCTION TIPS
• Is the title clear and limiting? Does it tell the user what to expect?
• Does the introduction provide a summary that tells the readers the purpose of the instructions?
• Are Warning, Caution, and Danger notices formatted so they convey the urgency/importance of the notice? Are the notices clearly visible to the user? Are the notices placed before or with the corresponding step?
• Are steps appropriately numbered to help guide the user? Are letters used to indicate any sub-steps of the numbered step?
• Are the steps in logical (chronological) order?
• Does each sentence provide only one step of the instructions?
• Do the instructions include an appropriate level of detail and technicality? Do they assume technical knowledge of the user or are the necessary details provided?
• Are the steps easy to understand? Does each step clearly explain what the reader should do? Does the writing use direct address, active voice, and imperative mood?
• Is each step visually separated so it is easy to locate?
• Are visuals used to help clarify the tasks?
• Is each visual and corresponding written step close together? Can the user easily understand which written step belongs to which image?
• Does the written instruction repeat what is shown in the visual so that the instructions do not rely on the visual image?
• Is bold or italics used to highlight or emphasize information? Are headings and sub-headings differentiated by font size? Are these elements used consistently throughout the document?
• Are the fonts are easy to read? (No more than two font families are used and fonts are used consistently throughout the document.)

Example Instructions

How to Change Front-Disk Brake Pads

How to Operate the Minolta Freedom 3 Camera

Standard Operating Procedures: Pouring Dental Impressions

This work "Instructions" is a derivative of Definitions, Descriptions, & Instructions CC-BY Amber Kinonen, Technical Definitions CC-BY Amber Kinonen, Technical Description: What Does it Look Like? CC-BY David McMurrey, and Technical Writing for Technicians CC-BY Will Fleming, used under a CC BY 4.0 license. "Instructions" is licensed under CC BY 4.0 by Mary P. Richards.