Transcript Insert Book Title Here

Technical Writing: Process and
Product
5th Edition
Steven M. Gerson
Sharon J. Gerson
Pearson Education/Prentice Hall
1
Chapter 12: Instructions and
User’s Manuals
This chapter discusses the following:
 Objectives
 Criteria for Writing Short Instructions
 Criteria for Writing a User’s Manual
 Process
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
2
Objective


People use equipment or make products
that require instructions—every day.
Examples:
NOTE:
operating machinery
 installing equipment
 maintaining
equipment
 testing components
 cleaning a product
 monitoring a system
 repairing equipment








troubleshooting a mechanism
caring for livestock
caring for plants
setting up a system
assembling a product
building a deck
making a cake
Gerson & Gerson: Technical Writing, 5th Edition
A primary job of
technical writers
is to write
instructions.
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
3
Criteria for Writing Short
Instructions (1-3 pages)

Title


Topic
Function (purpose of the instruction)
Topic
X320Z Radon Extractor
Installation Procedures
Function
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
4
Criteria for Writing Short
Instructions (cont.)

Organization

Introduction



Name the product
State the purpose of the instruction
List the number of steps
Product name
Purpose
The X320Z Radon Extractor removes hazardous gases from your
house. Installing this mechanism requires only 10 simple steps.
# of steps
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
5
Criteria for Writing Short
Instructions (cont.)

Organization (cont.)

Optional components

Required tools

Include graphics to help lay readers
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
6
Criteria for Writing Short
Instructions (cont.)

Organization (cont.)

Optional components

Hazards notations




Danger—the potential for death
Warning—the potential for injury
Caution—the potential for damage to equipment
Include icons for visual impact
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
7
Criteria for Writing Short
Instructions (cont.)

Sample hazard alert
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
8
Criteria for Writing Short
Instructions (cont.)

Organization (cont.)

Body



Organize steps chronologically
Develop points thoroughly
Conclusion






State warranties
Sell the product
Repeat the products uses
Provide corporate credentials or contact information
Provide a troubleshooting guide
Answer FAQs (frequently asked questions)
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
9
Criteria for Writing Short
Instructions (cont.)

Audience Recognition


Is your audience High-tech, Low-tech, Lay, or
combinations of all (Multiple)?
Write to your audience’s level of understanding.
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
10
Criteria for Writing Short
Instructions (cont.)

Graphics


People read instructions when they are
unfamiliar with a product.
Graphics help them visualize the steps.
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
11
Criteria for Writing Short
Instructions (cont.)

Style
1.
2.
3.
Number the steps (for future reference)
Use highlighting techniques (color for
hazards; graphics for visualization, for
example)
Don’t overload steps—one action per step
is enough.
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
12
Criteria for Writing Short
Instructions (cont.)
4.
Develop points thoroughly.


Define terms
Provide detailed steps
BAD—too vague
Add enough air to
inflate the tire.
How much is
“enough”?
Gerson & Gerson: Technical Writing, 5th Edition
Good Detail
Add air up to 32 psi (pounds per
square inch) to inflate the tire.
“Enough” is 32
psi (defined
parenthetically)
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
13
Criteria for Writing Short
Instructions (cont.)
5.
6.
Write concisely (short words, phrases,
and sentences).
Begin steps with verbs.
BAD
GOOD
1. You might want to
consider tightening the
clamp.
1. Tighten the clamp.
Without a verb, this is
not a required action.
Gerson & Gerson: Technical Writing, 5th Edition
The verb “Tighten”
makes the step a
required action.
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
14
Criteria for Writing Short
Instructions (cont.)
7.
8.
Personalize text with pronouns.
Do not omit articles (“a,” “an,” “the”).
Article
1. Use the 2” angle-edge brush to paint
your window ledges.
Personalized pronoun
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
15
Criteria for Writing a User’s
Manual (longer instructions)

Long User’s Manuals include all of the
topics already discussed:





Graphics
Hazards
Required tools
Detailed information geared toward the
audience
An appropriate style (numbered steps,
articles, verbs, personalization, etc.)
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
16
Criteria for Writing a User’s
Manual (longer instructions)

Long User’s Manuals include the
following additional information:

Cover page




Topic
Function (purpose)
Graphic
Table of contents
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
17
Criteria for Writing a User’s
Manual (longer instructions)

Introduction




Personalized, positive tone
Emphasizing the value and importance of the
instruction
Glossary—defining acronyms,
abbreviations, and high-tech terms
Technical descriptions (optional)
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
18
Criteria for Writing a User’s
Manual (longer instructions)




Warranties/guarantees (optional)
Parts lists/accessories (optional)
FAQs (optional)
Corporate Contact information
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
19
Process

To ensure the success of your
instruction,



Prewrite
Write
Rewrite
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
20
Process (cont.)

Prewriting techniques

Gather data, determine your audience,
decide on goals, and envision layout as
follows:



Brainstorm/list the components of your topic
Create a flowchart itemizing the steps in
chronological order
Use storyboarding to determine layout
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
21
Process (cont.)

Writing



Review the criteria for successful
instruction.
Review your prewriting.
Draft your text.
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
22
Process (cont.)

Rewriting

Revise the rough draft by







Adding detail for clarity
Deleting dead words and phrases for conciseness
Simplifying terms for easy understanding
Moving text for emphasis
Reformatting for easy access
Enhancing the tone
Correcting errors for professionalism
Gerson & Gerson: Technical Writing, 5th Edition
© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.
23