1 technical writing: process and product 5 th edition steven m. gerson sharon j. gerson pearson...

1

Technical Writing: Process and Product5th Edition

Steven M. GersonSharon J. Gerson

Pearson Education/Prentice Hall

2Gerson & Gerson: Technical Writing, 5th Edition

© 2006 Pearson Education, Upper Saddle River, NJ 07458. All Rights Reserved.

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



Objective

People use equipment or make products that require instructions—every day.

Examples: 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

NOTE:

A primary job of technical writers is to

write instructions.

NOTE:

A primary job of technical writers is to

write instructions.



Criteria for Writing Short Instructions (1-3 pages)

Title Topic Function (purpose of the instruction)

X320Z Radon Extractor

Installation Procedures

Topic

Function



Criteria for Writing Short Instructions (cont.)

Organization Introduction

Name the product State the purpose of the instruction List the number of steps

The X320Z Radon Extractor removes hazardous gases from your house. Installing this mechanism requires only 10 simple steps.

Product name

Purpose

# of steps




Organization (cont.) Optional components

Required tools Include graphics to help lay readers




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




Sample hazard alert




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)




Audience Recognition Is your audience High-tech, Low-tech, Lay,

or combinations of all (Multiple)? Write to your audience’s level of

understanding.




Graphics People read instructions when they

are unfamiliar with a product. Graphics help them visualize the

steps.




Style1. Number the steps (for future

reference)2. Use highlighting techniques (color

for hazards; graphics for visualization, for example)

3. Don’t overload steps—one action per step is enough.




4. Develop points thoroughly. Define terms Provide detailed steps

BAD—too vague

Add enough air to inflate the tire.

Good Detail

Add air up to 32 psi (pounds per square inch) to inflate the tire.

How much is “enough”?

How much is “enough”?

“Enough” is 32 psi (defined parenthetically)

“Enough” is 32 psi (defined parenthetically)




5. Write concisely (short words, phrases, and sentences).

6. Begin steps with verbs.

BAD

1. You might want to consider tightening the clamp.Without a verb, this is not a required action.

Without a verb, this is not a required action.

GOOD

1. Tighten the clamp.

The verb “Tighten” makes the step a required action.

The verb “Tighten” makes the step a required action.




7. Personalize text with pronouns.8. Do not omit articles (“a,” “an,”

“the”).

1. Use the 2” angle-edge brush to paint your window ledges.

Article

Personalized pronoun



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.)




Long User’s Manuals include the following additional information: Cover page

Topic Function (purpose) Graphic

Table of contents




Introduction Personalized, positive tone Emphasizing the value and importance of

the instruction Glossary—defining acronyms,

abbreviations, and high-tech terms Technical descriptions (optional)




Warranties/guarantees (optional) Parts lists/accessories (optional) FAQs (optional) Corporate Contact information



Process To ensure the success of your

instruction, Prewrite Write Rewrite



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



Process (cont.) Writing

Review the criteria for successful instruction.

Review your prewriting. Draft your text.



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

1 technical writing: process and product 5 th edition steven m. gerson sharon j. gerson pearson...

Documents

gerson gerson

technical writing

gerson sharon

upper saddle river

short instructions criteria

objectives criteria

th edition steven

product state