Writing User-Oriented Instructions and Manuals

1. Writing User-Oriented Instructions and Manuals Debopriyo Roy

2. We need Instructions • We need instructions for almost everything. • We need instructions to be short, simple and informal. • You might need instructions for yourself or you might want instructions to be designed such that someone can follow it.

3. Principle # 1 • Find out how much the Users know about the Task • Have users performed the task before? • Have they performed similar tasks? • Do users have the same background or knowledge of the task? • Will they have different purposes for using the instructions? Will their purposes for using the instructions change? • How much detail do users need to complete the task? Do they want only minimal instructions? • What are users’ attitudes toward the task and toward the equipment used for the task?

4. Writing Instructions • General Elaboration: Mowers tend to scalp lawns that have excess thatch. • How-to elaboration: Use vertical mowers specifically designed to remove thatch. When using these mowers, make sure the blades penetrate through the thatch to the soil surface.

5. Principle # 2 • Use an accessible design. • Will users use the instructions in an environment in which the instructions may become soiled or the pages crumpled? • Inside or outside typical office environment? • Must users read instructions from a distance? • What typeface is appropriate for the instructions? Do readers require a particular type size or page size to use the instructions effectively? • What layout will help users find and follow the instructions? • Not task oriented: Deletion, Modification, and addition • Deleting, Modifying, or Adding a Record

6. Tips for Design Layouts • Use a serif typeface such as Times Roman, Palatino, Ariel etc for the text. • Use no more than two typeface families. • Use a modified hanging or left-hanging format for headings. • When possible, use color consistently to highlight important elements such as first-level headings and lists. • Use typefaces, type sizes, color, and other design elements consistently.

7. Principle # 3: Use User-Oriented Language • Use action verbs – Replace the battery, Dial the phone number, press the power button. • Focus the users’ attention on the action (Imperative sentences). • Use simple language • Use language that users will understand • Use technical terminology when your users expect it. • If your users are not native speakers of English, avoid ambiguous language and terms.

8. Examples • Writer –style sentence: Testing of emergency numbers should be performed during off-peak hours. Organizing the meetings should always be done on the 2nd floor. • Imperative sentence: Test emergency numbers during off-peak hours. Always organize the meetings on the 2nd floor.

9. Principle # 4: Test Your Instructions • Usability testing is a process of conducting experiments with people who represent the users of a document. • The goal of usability testing is to determine how well the users understand the document and if they can safely and easily use it. • You can conduct usability testing on any technical document. The purpose is to test instructions and manuals. • Usability testing tells us: (1) Locate the information users need to perform the task and (2) Use the information to perform the task successfully and easily.

10. Test your Instructions • Have you determined the needs of the users? • Have you determined the purpose of the test? What do you want to learn from the test? • Does the test ask the participants to focus on specific problems? • Have you selected participants who are real users?

11. Logistics & Beyond • Before the tests, have you: • Reserved the testing room or facility? • Prepared a schedule for the testing day? • Have you distributed the schedule to the participants and observers? • Prepared to observe the participants as they use the instructions? • For the test, have you: • Explained the purpose of the test? • Told the participants how they should note problems or make suggestions? • After the test, are you ready to conduct an exit interview or debriefing with each participant? • Have you properly interpreted the results, drawn conclusions, and made recommendations?

12. Principle # 5 • Use the Appropriate Conventional Elements of Instructions and Manuals • The introduction should explain the purpose of the instruction, who should use it and what they can expect to learn, list all materials and equipments users would need, use visuals where appropriate, follow typographic conventions and consistent terminology and include warnings, notes and tips where necessary, include troubleshooting information, reference aids if needed.

13. Tips for Writing Safety Information • Place the safety alert before or next to the directions for the hazardous task, not after it. • Use a symbol or an icon to indicate a warning, danger, or caution. • Use a distinct color consistently for the safety alert. • Separate the safety alert from the text with white space or a border.

14. Examples • DANGER: Imminently hazardous situation which, if not avoided, will result in death or serious injury. • WARNING: Potentially hazardous situation which, if not avoided, could result in death or serious injury. • CAUTION: Hazardous situation which, if not avoided, may result in minor or moderate injury.

15. Tips for Writing the Theory of Operation / Description of Equipment Section • Use language users can understand. • Include only the details users need and expect. • Place this information near the beginning of the instructions or manual. • Generally, include a theory of operation or description of equipment only for more complex instructions or equipment.

16. Tips for Writing Step-by-Step Directions • Categorize the task into major steps and then divide these steps into sub steps. • Describe only one action in each step or sub step. • Number each step. • Use imperative sentences. • Use a list format, so users can follow the directions easily. • Use visual aids when appropriate.