Technical Writing: Process and Product 5 th Edition

Technical Writing: Process and Product5th Edition Steven M. Gerson Sharon J. Gerson Pearson Education/Prentice Hall

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: 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) Topic X320Z Radon Extractor Installation Procedures Function

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

Criteria for Writing Short Instructions (cont.) • Organization (cont.) • Optional components • Required tools • Include graphics to help lay readers

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

Criteria for Writing Short Instructions (cont.) • Sample hazard alert

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)

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.

Criteria for Writing Short Instructions (cont.) • Graphics • People read instructions when they are unfamiliar with a product. • Graphics help them visualize the steps.

Criteria for Writing Short Instructions (cont.) • Style • 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.

Criteria for Writing Short Instructions (cont.) • Develop points thoroughly. • Define terms • Provide detailed steps BAD—too vague Good Detail Add enough air to inflate the tire. Add air up to 32 psi (pounds per square inch) to inflate the tire. How much is “enough”? “Enough” is 32 psi (defined parenthetically)

Criteria for Writing Short Instructions (cont.) • 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. The verb “Tighten” makes the step a required action. Without a verb, this is not a required action.

Criteria for Writing Short Instructions (cont.) • 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

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

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

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)

Criteria for Writing a User’s Manual (longer instructions) • 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

Technical Writing: Process and Product 5 th Edition