1 Technical Communication A Reader-Centred Approach First Canadian Edition Paul V. Anderson Kerry Surman

2 Instructions Chapter 6

3 (c) 2007 Nelson, a division of Thomson Canada Limited Learning Objectives Apply reader-centred principles to instruction writing Apply reader-centred principles to instruction writing Describe four strategies specific to writing instructions Describe four strategies specific to writing instructions List five components of instructions List five components of instructions Outline strategies specific to online instructions Outline strategies specific to online instructions

4 (c) 2007 Nelson, a division of Thomson Canada Limited The Importance of Reader-Centred Instruction Writing You will need to prepare instructions on the job You will need to prepare instructions on the job – May be paper-based – May be online Instructions need to be usable and persuasive Instructions need to be usable and persuasive – Usability is the primary goal of instructions

5 (c) 2007 Nelson, a division of Thomson Canada Limited Special Challenges of Instruction Writing Readers repeatedly shift attention between reading and doing Readers repeatedly shift attention between reading and doing People only want to use one part People only want to use one part People need to understand term without prior knowledge People need to understand term without prior knowledge People dislike reading instructions People dislike reading instructions

6 (c) 2007 Nelson, a division of Thomson Canada Limited Four Strategies for Writing Instructions Write clearly and succinctly Write clearly and succinctly Use plenty of graphics Use plenty of graphics Design usable and attractive pages and screens Design usable and attractive pages and screens Test your instructions Test your instructions

7 (c) 2007 Nelson, a division of Thomson Canada Limited Write Clearly and Succinctly Choose words that convey meaning easily Choose words that convey meaning easily Construct sentences that are easily comprehended Construct sentences that are easily comprehended Use as few words as possible Use as few words as possible

8 (c) 2007 Nelson, a division of Thomson Canada Limited Use Plenty of Graphics Graphics are more effective than words for many purposes Graphics are more effective than words for many purposes Graphics don’t rely on language comprehension Graphics don’t rely on language comprehension Graphics can sometimes carry all the information Graphics can sometimes carry all the information

9 (c) 2007 Nelson, a division of Thomson Canada Limited Design Usable and Attractive Pages and Screens Good design help reorient readers when they return to your instructions Good design help reorient readers when they return to your instructions Design can help readers see connections Design can help readers see connections Attractive design can persuade readers to return Attractive design can persuade readers to return

10 (c) 2007 Nelson, a division of Thomson Canada Limited Test Your Instructions Ask members of your target audience to try out a draft Ask members of your target audience to try out a draft – Words and illustrations may be baffling – A step may be omitted – Page design may be confusing and unappealing

11 (c) 2007 Nelson, a division of Thomson Canada Limited Structure of Instructions Simple instructions contain only the directions Simple instructions contain only the directions More complex instructions contain some or all of five elements More complex instructions contain some or all of five elements Consider Consider – Readers’ aims and needs – Characteristics shaping the way they read and respond

12 (c) 2007 Nelson, a division of Thomson Canada Limited Five Components of Instructions Introduction Introduction Description of the equipment Description of the equipment List of materials and equipment needed List of materials and equipment needed Directions Directions Troubleshooting Troubleshooting

13 (c) 2007 Nelson, a division of Thomson Canada Limited Answer Your Readers’ Questions Introduction Introduction – Will these instructions help me? – How can I use them effectively? Description of the equipment Description of the equipment – Where are the parts that I’ll be working with while I repair or use this equipment? List of materials and equipment needed List of materials and equipment needed – What should I collect before I begin?

14 (c) 2007 Nelson, a division of Thomson Canada Limited Answer Your Readers’ Questions (continued) Directions Directions – Once I’m ready to start, what – exactly – do I do? Troubleshooting Troubleshooting – Something isn’t working correctly – How can I fix it?

15 (c) 2007 Nelson, a division of Thomson Canada Limited Introduction Subject Subject Aim Aim – Purpose or outcome of the procedure described Intended readers Intended readers – Is this manual for me? Scope Scope – Specific tasks readers want to perform Organization Organization

16 (c) 2007 Nelson, a division of Thomson Canada Limited Introduction (continued) Usage Usage – Advice about how to use the instructions most effectively Conventions Conventions – Explanations of shortcut expressions Motivation Motivation – Reasons why readers should use the instructions Safety Safety

17 (c) 2007 Nelson, a division of Thomson Canada Limited A Special Note About Safety Meet your ethical obligations Meet your ethical obligations – Readers depend on you Meet your legal obligations Meet your legal obligations Provide warnings that are Provide warnings that are – Prominent – Easy to understand – Persuasive

18 (c) 2007 Nelson, a division of Thomson Canada Limited Principles of Writing Warnings Make your warnings stand out visually Make your warnings stand out visually Place your warnings so that your readers will read them in time Place your warnings so that your readers will read them in time State the nature of the hazard and the consequence of ignoring the warning State the nature of the hazard and the consequence of ignoring the warning Tell your readers what steps to take to protect themselves Tell your readers what steps to take to protect themselves

19 (c) 2007 Nelson, a division of Thomson Canada Limited Definitions of Warnings Caution Caution – Alerts readers that they may spoil the results Warning Warning – Alerts readers that they may damage equipment Danger Danger – Alerts readers to the danger of injury or death

20 (c) 2007 Nelson, a division of Thomson Canada Limited Description of the Equipment Readers need to know the location of parts to operate or repair Readers need to know the location of parts to operate or repair Readers sometimes need to know the function as well Readers sometimes need to know the function as well Illustration may be accompanied by written descriptions Illustration may be accompanied by written descriptions – See Figure 6.1, page 149

21 (c) 2007 Nelson, a division of Thomson Canada Limited List of Materials and Equipment Needed Present the list of items not normally at hand Present the list of items not normally at hand Present the list before the directions Present the list before the directions

22 (c) 2007 Nelson, a division of Thomson Canada Limited Directions Write each direction for rapid comprehension and immediate use Write each direction for rapid comprehension and immediate use Help your readers locate the next steps quickly Help your readers locate the next steps quickly Within steps, distinguish actions from supporting information Within steps, distinguish actions from supporting information

23 (c) 2007 Nelson, a division of Thomson Canada Limited Directions (continued) Group related steps under action- oriented headings Group related steps under action- oriented headings Use many graphics (Figure 6.2, page 150) Use many graphics (Figure 6.2, page 150) – Where things are (Figure 6.3, page 152) – How to perform steps (Figure 6.4, page 153) – What should result (Figure 6.5, page 154)

24 (c) 2007 Nelson, a division of Thomson Canada Limited Directions (continued) Present branching steps clearly Present branching steps clearly Tell what to do in the case of a mistake or an unexpected result Tell what to do in the case of a mistake or an unexpected result – Anticipate places where readers might make mistakes – Tell readers how to correct or compensate

25 (c) 2007 Nelson, a division of Thomson Canada Limited Troubleshooting Tells reader what to do if things don’t work out as expected Tells reader what to do if things don’t work out as expected A table format works best A table format works best – See Figure 6.6, page 155

26 (c) 2007 Nelson, a division of Thomson Canada Limited Physical Construction of Instructions Adapt your instructions to the physical environment in which they will be used Adapt your instructions to the physical environment in which they will be used – Crowded workspace – Wet or windy workspace

27 (c) 2007 Nelson, a division of Thomson Canada Limited Writing Online Instructions Keep each unit of instruction to screen size or smaller Keep each unit of instruction to screen size or smaller Use a consistent design on all instructional screens Use a consistent design on all instructional screens Let readers see their work areas simultaneously with your instructions Let readers see their work areas simultaneously with your instructions

28 (c) 2007 Nelson, a division of Thomson Canada Limited Writing Online Instructions (continued) Provide a map or table of contents on the home page Provide a map or table of contents on the home page Provide navigational aids within the instructions Provide navigational aids within the instructions Conduct a usability test Conduct a usability test

29 (c) 2007 Nelson, a division of Thomson Canada Limited Sample Instructions Set of lab instructions written by a student Set of lab instructions written by a student – See Figure 6.7, page 157 Online instructions Online instructions – See Figure 6.8, page 162

30 (c) 2007 Nelson, a division of Thomson Canada Limited In Summary Ensure your instructions are usable first, then persuasive Ensure your instructions are usable first, then persuasive Apply the four strategies specific to writing instructions Apply the four strategies specific to writing instructions Include the five components of complex instructions Include the five components of complex instructions Use the six strategies specific to online instructions Use the six strategies specific to online instructions