Writing Task-Oriented Instructions

A little story before you begin reading this page:

Technical writers strive for clarity, precision, conciseness, and readability in all documents. In task-oriented text, or instructions that explain how to assemble, operate, or maintain a product, a breakdown in any one of the key areas discussed in this article can result in damaged equipment and, more seriously, confused or injured users.

You can add depth to your understanding of the genre of instructions (such as tutorial, referential, procedural, and job aids) by reading Philip Rubens' discussion covering the types and characteristics found in Science and Technology Writing: A Manual of Style, 2nd edition: click here 

While these guidelines are useful in writing for users at all levels of technical skill, they are particularly helpful for those who aren't experts. Non-expert users want information they can understand immediately without reading a lot of explanation. They need precise information written in simple language and presented in an easy-to-follow format. In this website, we discuss using visuals [illustrations] and describe guidelines to use when you write the prose for task-oriented information. We also provide a variety of examples. However, always write to your target audience.

    Visuals [Illustrations] in Task-Oriented Instructions

Visuals will enable users to "see" how to complete instructions. Technical writers and editors need to become familiar with the wide range of possible visuals appropriate for instructions as well as which types are best for the target audience and subject of the instructions.

Once I read that instructions for task-oriented instructions should be 50 % prose and  at least 50% or more visuals [illustrations]. Think about instructions for assembling a product. Most effective might be 90% visuals or even 100% or all visuals. Such instructions for international markets resolve difficulties in translating them.

My son and I once found a tremendous bargain on model robots to assemble (25 cents each!). Why the price? The instructions were in Japanese and not many living in Stillwater, OK, read Japanese. We purchased them anyway. No, neither of us read Japanese. What I discovered, however, were excellent examples of visual presentation for assembly instructions. For example, dotted arrows indicated how to put parts into parts (a version of an exploded diagram). The pictures told us what colors to use.

On the other hand, employee manuals, which are instructions, but not primarily task- oriented instructions, don't require as many visuals. Their effectiveness, however, can be increased by using tabular presentation (informal and formal tables) as well as annotated forms and samples of completed forms.

Some visuals especially appropriate for instructions for products are tables, flowcharts, schematic diagrams, photographs, and drawings (including line drawings, exploded drawings, cutaway drawings, and cross-sections). Some use clip art as well. Although your first inclination might be to use photographs, because they represent objects realistically, often background clutter as well as "object clutter," may distract from the part important to the instructions.

Visuals for computer manuals.  Common visuals found in computer manuals are tables, flowcharts, photographs, and drawings such as ones of computer keys and screens.

Tables summarize content and present it in a visual format that makes information both accessible and more easily understood than if it is expressed in prose passages. Flowcharts provide visual overviews that help readers build schemata about processes to be completed. Drawings such as computer keys and computer screens ("screen shots") indicate computer keys that readers press, information that they type, and content that they see on the computer screen. These visuals prevent readers from confusing different types of content. Be sure that you use such visuals consistently to enable readers to form schemata.

Prose in Task-Oriented Instructions

This section contains three sub-sections, describing guidelines for achieving overall clarity, for writing sentences that work, and for selecting the right words.

     Prose Guidelines: Overall Clarity

You'll find four general guidelines explained in this section.

1. Group instructions in sets of no more than 5 to 9 steps. If a procedure requires more than 7 to 9 steps, subdivide the procedure and use headings to indicate the subdivisions.

How can you as a writer enable users to readily digest a lot of information about unfamiliar tasks? If you provide a framework indicating what specific task is being performed at each stage of the process and then clearly identify the actions required to perform each task, users can more easily link information.

For example, consider the section below about testing a machine from a work management manual. Operators encounter a list of 23 single-spaced directions. Such instructions actually test their ability to perform tasks without understanding the stages in the process, the relationship of one series of steps to the next, or the changes they should notice as they complete each step of the process. The writer has not interpreted the bits of information.
 

Before writing the first step in task-oriented prose, organize the information according to the tasks which users need to perform. Group the information in manageable chunks; that is, a task involving numerous steps should be organized as one task with several substeps. This "chunking" of information signals a workable road map that helps users proceed from one task to the next.

Remember Miller's "Magical Number Seven." Because people can process only so much information, he recommends organizing data into groups of five to nine items (referred to the rule of "7 plus or minus 2"). However, we would recommend groupings of no more than seven steps in task-oriented text ("5 plus or minus 2"). You can find this work by Miller in "The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information." Psychological Review 63 (1956): 81-97.

An aside about this grouping of items -- think about how we write, and probably remember, phone numbers (252-328-0000), zip codes (75858-4353), and social security numbers (xxx-xx-xxxx). Although these items total 9 to 10 items, note how we "group" them in 2 to 5 items.

Back to the subject at hand, the information about testing a machine. Note the difference in the instructions presented above with the same information "chunked" or "grouped" in logical sequences for users.
 

Original	Revised
1. Engage purge cycle -- cycle set for 10 sec. auto.  2. Engage the DC voltage button. Adjust voltage adjustment knob to required test voltage. (See correct "Electric Drive Unit Test -- Preliminary Form" for the model being tested.)	1. Prepare the machine for the test. Engage purge cycle -- cycle set for 10 sec. auto. Engage the DC voltage button. Adjust voltage adjustment knob to required test voltage. (See correct "Electric Drive Unit Test -- Preliminary Form" for the model being tested.)
3. Shift the "Joy-Stick" to the "Test Left" mode. 4. Engage "Input RPM" button and record the results.  5. Record DC Amps on the same form.  6. Engage "Output RPM" button and record results.  7. Record output torque.	2. Test the Left Function. Shift the "Joy-Stick" to the "Test Left" mode. Engage "Input RPM" button and record the results. Record DC Amps on the same form. Engage "Output RPM" button and record results. Record output torque.
8. Shift the "Joy-Stick" to the "Test Right" mode. 9. Engage "Input RPM" button and record results. 10. Record DC amps. 11. Engage "Output RPM" button and record results. 12. Record output torque.	3. Test the Right function. Shift the "Joy-Stick" to the "Test Right" mode. Engage "Input RPM" button and record results. Record DC amps. Engage "Output RPM" button and record results. Record output torque.
13. Shift the "Joy-Stick" to "Brake Cycle" mode. (Run in Rev.) 14. Adjust "Brake Pressure" to 200 lbs. 15. Engage "Brake Cycle" button. Brakes will run through brake burnish cycle for 2 mins. Cycle complete will be indicated when "Brake Cycle Test Complete" light comes on. 16. Release brake pressure.	4. Test the Brake Cycle. Shift the "Joy-Stick" to "Brake Cycle" mode. (Run in Rev.) Adjust "Brake Pressure" to 200 lbs. Engage "Brake Cycle" button. Brakes will run through brake burnish cycle for 2 mins. Cycle complete will be indicated when "Brake Cycle Test Complete" light comes on. Release brake pressure.
17. Shift "Joy-Stick" to the "Test Left" mode. 18. Engage "Ratio" button and record results. 19. Increase absorber pressure to inch/pounds called for on "Preliminary Form" for appropriate mode. Read off digital display. 20. Engage "Output RPM" button and record results. 21. Engage "Input RPM" button and record results.	5. Test the Left Function a second time. Shift "Joy-Stick" to the "Test Left" mode. Engage "Ratio" button and record results. Increase absorber pressure to inch/pounds called for on "Preliminary Form" for appropriate mode. Read off digital display. Engage "Output RPM" button and record results. Engage "Input RPM" button and record results.
22. Record DC Amps.  23. Shift "Joy-Stick" to the "Test Right" mode. Reset absorber. 24. Engage "Output RPM" button and record results. 25. Engage "Input RPM"  button and record results. 26. Record DC Amps.	6. Test the Right Function a second time. Record DC Amps.  Shift "Joy-Stick" to the "Test Right" mode. Reset absorber. Engage "Output RPM" button and record results. Engage "Input RPM"  button and record results. Record DC Amps.

When users will probably be performing the steps as they read the instructions, grouping the steps helps them "see where they are," understand what they are doing, and complete the process without mistakes..

2. Give specific content, not general. Be quantitative, not relative.

Compare the following instructions.
 

The examples in the left column could cause users, especially non-experts, varying degrees of difficulty. Those statements assume a pre-existing knowledge base on the part of users -- a knowledge that non-experts do not have. You, as writer, may know that users must allow 12 hours for a fiberglass coating to "dry adequately," but you cannot assume that all users, even experts, know that fact. As you read each sentence in task-oriented text, look for general statements that you can make more specific, more exact, more quantitative.

3. State meaning clearly and directly. This guidelines involves giving specific, not general content (general, #2); writing "short" sentences (sentences, #4, below), and choosing easily understood words (words, #2, below).

If users have to interpret instructions or supply more detail than given in the instructions, they may not perform the tasks as intended. If you write specific, short sentences and choose easily understood words, you improve the clarity of the content. Consider the following examples.
 

Using simple, concrete words and uncomplicated sentence structure increases clarity in instructional prose. An aside: you should write to users. For instructions for experts in a field, what may seem simple words for them would not be simple words for the general public.

4. Separate instructions from other explanations. Give instructions first: that is, put important information first. Don't confuse readers by intertwining these two different types of information: one procedural (instructions) and the other descriptive (explanations).

As you write task-oriented prose, always remember that your users want to perform actions. Give instructions first. Tell them how to perform the action first, then, if necessary, explain the reasons for or results of that action. Compare the following instructions for software users.
 

Glancing at these words, users may not see the instructions buried within the paragraph and skip on to the next information. The procedure is much easier for users to perform if you give the instructions first and then the related explanation.
 

Separating instructions from explanations makes it easier for users to process these two types of information that function in different ways. Users, as a result, understand what to do and are reassured by knowing what to expect from their actions. Note the following example.
 

In this case, just when users, especially first-time users, think that they have completed a document and are printing it, the appearance of an "Opening Menu" can be confusing. They may think that they have not completed the instructions correctly. By telling them what to do first and then what to expect to see, you can eliminate that confusion.

Sometimes you need to let users know why a particular action is important. However, you may lead users to skip what they may view as unnecessary descriptive prose if you state the reason for performing an action before you state how to perform the task itself. Consider the following example that provides important information about a temperature guard.

Prose Guidelines: Writing Sentences

This section contains 5 guidelines for writing sentences in task-oriented prose.

1. Use second-person imperative verb form (command form). Bottom line -- Use verb-first sentences.

Remember that, in task-oriented prose, users want to know what action to perform -- what verb to do. If the first word of each procedure states what users are to do, then they are more likely to understand what action they should perform in each step.

Consider the following example: "The door to the disk drive should be closed." Upon reading that statement, users will first check to see that the door is closed. If it is not, they will probably assume that it should be and close it. By beginning the sentence with the verb, you speak directly to users and clarify what they are to do, so that they perform the action quickly without having to interpret your information. That is, write "Close the door to the disk drive."

In the following examples, notice how you can reduce the risk of confusing users by beginning sentences with verbs.
 

In addition to improving clarity, you also gain emphasis by writing verb-first sentences. In general, readers pay more attention to information placed at the beginning and at the end of sentences than to information placed in the middle of a sentence. Verb-first sentences take advantage of that point of emphasis to signal each task to the user.

2. If there are conditions related to performing the action -- conditions such as when or how to perform the actions -- begin sentences with short phrases or clauses conveying these conditions. In those cases, write condition-first sentences. Think about those users who read and perform instructions concurrently. Such initial information may prevent them from losing data in software programs, damaging equipment, or injuring themselves.
 

If not observing the conditional would damage equipment, or, more importantly, injure or kill employees, then state the condition first, but also highlight it . Or format the information as a warning.
 

3. Put one instruction or idea in a sentence unless the instructions or ideas are related and simple (not complex).

The visual format of a sentence suggests one idea or two closely related ideas; in the case of instructional writing, one action. If you tell users how to complete more than one task in a sentence, you may confuse them. They must perform one task and then return to the sentence to discover the next task to be completed.

Consider the following instructions written for operating machinery:
 

Those familiar with this operation would probably find these instructions easy-to- follow, but for the novice users, the sentence contains too much information. When users need to divide a sentence into separate performance steps, then the sentence contains too much information.

The following revision clarifies the procedure by presenting one instruction or two closely related instructions in a sentence:
 

In a previous example, a revision of "Turn on the computer" could have read as "Locate the red toggle switch at the back of the computer and press it down." That sentence actually contains two instructions, two actions to complete: "locate" and "press." In that situation, users who locate the switch will probably still have their fingers on it when they read "press it down." It seems reasonable, then that this information is not too much to place in one sentence.

4. Write "short" sentences (how short or how long is determined by the complexity of the content).

When writing instructions, you want to present information clearly and simply. Short sentences often are more useful in reaching this goal than are longer sentences because they normally make it easier for users to perform the instructions as they proceed. While definitions of "short" range from no more than 10 to no more than 20 words, we would recommend that you average 14 to 18 words in task-oriented prose. If you find that your sentences exceed that average, watch for needless words, excess information, or more information than users can remember or apply.

Consider the following examples.
 

When you want to make complicated procedures less complicated, use less complicated sentence structure. Keeping this guideline in mind may help you achieve some of the other guidelines suggested in this website. For example, if you keep sentences short, you will be less likely to put more than one instruction in a sentence or to instruct and explain at the same time.

Occasionally, writers are trapped between the guidelines to keep sentences short and the need to provide complete information on a step that may require a long series of words, phrases, or clauses. Creative writers use "sight rhyme" to create the illusion of rhyme, even when phonetic support for it does not exist. Similarly, technical writers should create sentences that appear "short on sight" even if these sentences contain many words.

In the following example, note that the information in the original looks shorter when presented in a vertical, bulleted list that maintains the appearance of a short sentence. In addition, the revised version indicates the "general" action ("typing in patient information").
 

 5. Use positive statements. Don't use negative statements, if possible. Especially avoid using several negatives. If readers are likely to complete a negative action, state the instruction positively and then indicate the negative. For example, write

• Submit university receipts with request-for- reimbursement form. Don't forget to submit proof of payment received from the university.

Note the following example:
 

The problem inherent in each of these statements is that users know what not to do, but they must figure out what to do. Some users may know what to do and be able to translate the negative action suggested into a positive action, but other may not be able to translate the negatives. In the example above, how should the unit be cleaned? Should the card be attached in any way to the completed form? For what tasks should this dryer be used? How should users move to the next line in the table?

Positive statements tell users what to do:
 

However, suppose that you do want users to know what to do, but you are concerned that users will complete an action that they should not complete. In that situation, state the positive action first and follow with instructions about what not to do.

See the examples below.
 

Prose Guidelines: Writing the Words

This section contains three guidelines for writing words.

1. Use terms consistently. Don't change terminology (words).

Some users are not only performing tasks for the first time, but also working with materials, parts, or equipment for the first time. You can help them use a product properly if you select and use one term consistently to refer to each part or piece of equipment. If several words can be used, indicate all the terms are accurate and tell users which term you will use.

For example, the following instructions explain in three short steps how to connect a UHF antenna to a VCR system.
 

Many non-expert users might find these instructions difficult to follow for one reason: they do not realize that the "antenna connector,"  the "transmitter," and the "terminal" refer to the same piece of equipment. The example below demonstrates that using terms consistently adds to clarity in the revised example:
 

As you write the prose for instructions, avoid using synonyms or varying terminology to achieve a more sophisticated style. Use terms consistently to help users compete tasks.

 2. Use easily understood, common words. Use concrete words, not abstract ones.

Don't use words that are more technical than needed or that are more complex than needed. Your best choice is the shortest, most exact, and easily understood word.

Compare the following example.
 

Although "disengage," "juxtaposed," and "digit" are not technical words, "remove," "close," and "finger" are easier for most users to understand quickly.

3. Use function words (articles, conjunctions, and prepositions) for clarity. For example, use the indefinite articles "a" and "an," or the definite article "the".

While sentences should be "short," they must also be natural and fluent. Sometimes, in the attempt to keep sentences short, writers "telegraph" instructions by omitting functions words, such as articles, conjunctions, and prepositions. The result not only disrupts natural style, but also increases the possibility for confusing the users because words that signal the relationships between the words are omitted.

In the following example is the user to report problems in materials for the "sealed refrigeration system" or problems in "system materials" for sealed refrigeration? By including function words, you untangle the words for users.
 

In the following example, a first-time user might look for two lines to "turn off": the water supply line and the clear line. Adding articles clarify meaning.
 

Because the writer eliminates function words in the following examples, the information is conveyed by the words is incomprehensible. Users must pause and separate "active cold water supply line point." Some of them might not arrange the words to achieve the intended meaning.
 

We should note that it is not always necessary to include every function word easily understood in the sentence. The example below illustrates this situation.
 

Remember that you can condense meaning too much in your effort to write short sentences for instructions. Use function words when they help users understand how the words in your instructions relate.

Examples of Task-Oriented Instructions

The example employee handbook created by John Burns illustrates also the guidelines about writing sentences and words: go to http://core.ecu.edu/engl/southards/tips/ssBurns/index.htm