Technical Writing: Process and Product 5th 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

A primary job of technical writers is to write instructions. Objective People use equipment or make products that require instructions—every day. Examples: NOTE: A primary job of technical writers is to write instructions. 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

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

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