best practices for writing and editing user/instruction manuals
DESCRIPTION
This presentation outlines industry best practices in writing/editing “user friendly” instruction/user manuals. Instruction/user manuals are written for the purpose of helping the end-user complete a task. These documents must be clear about its purpose. The technical writer must take into consideration the user’s attitude, education, and experience when composing such documents. Methods of organization include a table of contents, pagination, previews and reviews, cross references, glossary, and Index - alphabetical list and page numbers - for longer docs for ease of use. Warnings, cautions, and dangers should also be used throughout the text where appropriate. Appropriate visuals should be used only as needed to aid the user in understanding of the task at hand.TRANSCRIPT
INSTRUCTION MANUALS
Best practices for documenting user instructions and creating user manuals
INSTRUCTIONS
Documents to help a reader complete a task• Actions - personnel (behavior)• Assembly - objects/mechanism• Operation - equipment• Implementation of a process
TASK & AUDIENCEANALYSES
Be clear about purpose• Regardless of user, task is same• What exactly will user be able to do?• Caution users by incorporating
guidelines/materials needed• What knowledge/experience do users
need?
DO A FULL AUDIENCE ANALYSIS
Complete this form and translate to prose
Know how this analysis affects the instructions, i.e. User attitude - justify steps or entire doc? User education - tech level, defs, visuals?User experience - prior knowledge, details?
TRANSLATE TO PROSE
DESIGN
Consider:• Quality of paper• Frequency of use• Ease of usability• Chunking• Labeling• Parallel structure
ORGANIZING A MANUAL
What sections are needed?• Introduction
• Background (identify intended users) “These instructions are for technical writing students who will produce analytical reports…”
• Info about how to use manual• Overview, general defs, description, and functions of
the equipment process• Theory of operations for those who need to know
why, not just what• Project history
SECTIONS (cont’d)
Instructions• Actual steps to perform task - be sure
they are logical, sequential and clear• Choose a consistent structure• Consider time element
SUPPORT
Frequent Users’ Guide• List summarizing steps• Placement (follows full instructions)• Consider use - plastic cover?
Trouble-shooting & Maintenance• Anticipate (use testing to discover)• Matrix
DEVICES FOR LOCATING INFORMATION
Table of Contents Pagination - consider dual #s Previews and Reviews Cross References Glossary Index - alphabetical list and page
numbers - for longer docs
CONTENT ELEMENTS
Precise Title - includes purpose: “Operation Manual for Regal Slow Cooker” - may use visuals
Necessary components: parts, equipment, materials, steps, accurate chronology
Clear, direct working definitions -parenthetical in steps, glossary or appendix, and consistent terminology
Content Elements (cont’d)
Accurate relevant details only Appropriate justifications - Is
rationale needed for step? Necessary Warnings and Cautions Style and Grammar conventions
DICTION
Use verb instead of noun for actual steps, “Turn lever…,” not “Lever should be turned…”
Be consistent Include appropriate details Include rationale for steps only if
task/audience analysis indicates (consider personal injury)
Diction (cont’d)
Warnings - death or danger Cautions - hazards Dangers - immediate
Label & separate visually Identify the risk
Describe the risk Provide instructions to avoid
VISUAL AND DESIGN ELEMENTS
Illustrate parts, sequence of steps, positioning of operator/equipment, development of change of object
Appropriate visuals used only as needed (flowchart, diagrams, infographics)
Include textual ref, I.d., title Balanced visual and verbal content accurate visuals, easily understood Labeled visuals with relevant text Appealing, usable format
