Chapter 19

Writing Instructions and

Manuals

2Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Understanding the Writing Process for Instructions and Manuals

Analyze your audience and purpose.

Gather and organize your information.

Design the document. Draft the document. Revise, edit, and proofread the

document. Conduct usability tests of the

document.

3Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Questions to Consider in Designing a Set of Instructions

What are your reader’s expectations?

Do you need to create more than one set of instructions for different audiences?

What languages should you use? Will the environment in which the

instructions are read affect the document design?

4Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Questions to Consider in Designing the Pages

Should you make your pages multilingual?

Will readers be anxious about the information?

Will the environment in which the instructions are read affect the page design or typography?

5Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Guidelines for Designing Clear, Attractive Pages

Create an open, airy design.

Clearly relate the graphics to the text.

6Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Elements of a Set of Instructions

Title General introduction

Safety information Step-by-step instructions Conclusion Example

7Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Forms of Titles for Instructions

Title should be simple and clear! Title should describe the activity to be

performed Use verbs

Effective titles: How-to. “How to Install the J112 Shock

Absorbers” Gerund. “Installing the J112 Shock

Absorber” Ineffective titles:

Noun strings. “J112 Shock Absorber Installation Instructions”

8Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Questions to Answer in Drafting the Front Matter of a Manual

Who should use this manual? What product, procedure, or

system does the manual describe? What is the manual’s purpose? What are the manual’s major

components? How should the manual be used?

9Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Questions to Consider in Drafting Introductions for Instructions

Who should carry out the task? Why should the reader carry out

this task? When should the reader carry out

this task? What safety measures or other

concerns should the reader understand?

What items will the reader need? Materials list

How long will the task take?

10Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Steps in Planning for Safety

Write effective safety information. Design effective safety

information. Place safety information in the

appropriate location.

11Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Steps in Planning for Safety

Write effective safety information. Be clear and concise “Safety glasses required”

Design effective safety information. Prominent & easy to read Use of symbols

Place safety information where reader is most likely to see it! Repeat if necessary!

Example – text Example - symbols

12Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Signal Words in Safety Labels

Danger: an immediate and serious hazard that will likely be fatal

Warning: potential for serious injury or death or serious damage to equipment

Caution: potential for anything from moderate injury to serious equipment damage or destruction

Note: a tip or suggestion to help readers carry out the procedure successfully

DANGER

WARNING

CAUTION

13Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Guidelines for Drafting the Body

Structure the body according to how the reader will use it.

Write clearly. Be informal, if appropriate. Use graphics.

14Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Guidelines for Drafting Steps in Instructions

Number the instructions. Present the right amount of information in

each step. Use the imperative mood.

“Attach the red wire…” Don’t confuse steps and feedback

statements. “Insert disk” vs. “The system will now update…”

Include graphics. Do not omit the articles (a, an, the) to save

space. Example

15Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Drafting the Conclusion

Assume the reader has completed the task

What should be the reader’s next steps

Maintenance tips Troubleshooting guide

16Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Two Approaches to Revising a Manual

Publish a "new" manual. Publish a "revised" manual.

17Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Questions to Consider in Planning Manuals for Multicultural Readers

In what language should the information be written?

Do the text or graphics need to be modified?

What is the reader’s technological infrastructure?

18Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Basic Principles of Usability Testing

Applicable for product testing as well as documentation testing Particularly with installation

manuals It permeates product

development. It involves studying real users as

they use the product. It involves setting measurable

goals and determining whether the product meets them.

19Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Planning a Usability Test

Understand your users’ needs. Determine the purpose of the

test. Staff the test team. Set up the test environment. Develop a test plan. Select participants. Prepare the test materials. Conduct a pilot test.

20Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Important Aspects of Conducting the Usability Test

Staying organized Interacting with the participant Debriefing the participant

21Chapter 19. Writing Instructions and Manuals © 2007 by Bedford/St. Martin's

Interpreting and Reporting the Data

Tabulate the information. Analyze the information. Report the information. Modify the product/manual and

re-test if necessary.