Lesson 11
User Guides
Introduction: Connecting Your Learning
Think about the last time you bought a phone, a car, or even an alarm clock. All of these products have features that may require special instructions in order to be used safely and correctly. The manufacturers of these – and many other products – generally provide user guides with the products. In this lesson, you will write a user guide for a product.
Readings, Resources, and Assignments
Required Textbook Readings Review previously read chapters as needed.
Multimedia Resources Writing a user guide (in two parts):
Technical Writing in 20 minutes – Part 1
Technical Writing in 20 minutes – Part 2Required Assignments 1. Write a user guide.
Check Prior Knowledge
Consider whether the following statements are true or false.
1. An index is optional for a lengthy user guide.
True
False
2. User guides should include safety information and legal disclaimers.
True
False
3. Poorly written user guides can lead to dissatisfaction with good products.
True
False
4. A good user guide can be written in one draft.
True
False
5. The organization of a user guide doesn’t matter if the content is correct.
True
False
Focusing Your Learning
Lesson Objectives
By the end of this lesson, you should be able to:
1. Define the elements of a user guide/manual.
2. Write a user guide.
Key Terms
Key terms are important words for you to learn in this course. They will be defined in either your lesson or reading. Be sure to learn these by the end of the lesson and record them in your notes.
• Table of contents
• Product specifications
• Parts
• Procedures
• Warnings
• Legal notices
• Frequently asked questions
• Company contact information
• Index
Instruction
Because of the way most people read user guides, writers must carefully consider how to best organize the guides to make them most accessible to consumers. Consider this. How might you react if you bought an amazing widget but couldn’t get it to work? Would you be happy to have a widget because you have heard how amazing it is? No way! You want a functional widget, and if it doesn’t work, you expect to be able to find answers quickly. Say you go right to the user guide for your widget and begin to look for the section on sounds/alerts. How would you feel if you opened the guide to find a long, essay-format block of text with no headings, no index, no table of contents, and no bold/italics to help you pick out key words? In this scenario, you would probably have to read the whole guide to find the answer to your question. Reading the whole guide might be time consuming, and it would probably be annoying; you want to use your widget, not read about it. Since you can’t find your answer in the user guide, you call customer support. When you finally get through to customer support, you get an answer to the question about sounds/alerts and go back to using your widget. Later, you realize you can change the background of your widget. You try to figure it out on your own, but you can’t. You flip through the user guide and then call customer support again, and your feelings of frustration mount. You think about returning the widget, and, of course, you tell your friends and family that the widget seems cool but that it is a pain to use and you wish you’d bought a whatsit instead.
Remember that technical writing is practical writing. User guides are some of the most practical writing you can find because they help users learn how to use products. When a person buys a product, he or she wants to be able to use it correctly as soon as possible. A well-written user guide allows readers/customers to do just that.
User guides also contain safety information about products. Readers must be alerted to any potential hazards of the product and how to avoid injuries. Warnings can help product manufacturers avoid costly lawsuits, negative press, and excessive calls/visits to customer service centers.
Think for a moment about the user guides you have read recently. Did you read the whole thing cover to cover? If you’re like most people, chances are that you have not. More often than not, people jump into using the product and try to figure it out without reading the guide. Usually, consumers turn to user guides when they realize they are unable to figure out a step on their own. When this happens, do you think consumers will read the guide cover to cover? Of course not. They will look for the section that contains the information needed at that moment to solve a particular problem, as you did in the widget scenario.
Writers must consider how to best meet the needs of readers when creating user guides. As you saw in the example about the widget, unclear user guides can cost businesses money in terms of lost sales, returned merchandise, and providing additional customer service. Effective user guides enhance products and companies by making it easy to find and use information about the product.
The above text sounds good in theory, but what steps can you take to create a good user guide?
Creating User Guides
User guides require thinking about customers’ needs in terms of what content is included in the guide and how that content is organized and presented. Ideally, you should include just the right amount of information for the guide’s audience. Readers will be bored by excess information not related to using the product, and they will be upset about missing information they need. Think carefully about what to include and what not to include. Work through the brainstorming process to ensure you’ve considered as many angles and topics as possible before you begin planning and writing.
The planning phase for writing user guides is critical. This type of document requires careful organization and structure to support a user’s desire to find information quickly. Elements of organization that you may want to include are:
• Table of contents
• Product specifications
• Parts
• Procedures
• Warnings
• Legal notices
• Frequently asked questions
• Company contact information
• Index
Tying it all together
Remember to apply the elements of design you learned about in Lesson 8. Visual elements, such as diagrams, consistent headings, bullets, and numbering, can go a long way toward enhancing the meaning of the text and helping readers efficiently navigate the content of the user guide.
When writing the user guide, make sure you use language/vocabulary appropriate for the audience. A user guide for network engineers would use different language than a user guide for Windows 7 software.
• Use a tone that is authoritative yet friendly.
• Be direct and concise.
• Check spelling and grammar.
• Avoid large blocks of text.
Watch the following videos for a detailed explanation of the process for writing a user guide.
Before beginning your assignment, you may want to review all of the previous lessons to help you refresh your memory.
Assessing Your Learning
Graded Assignments
Lesson 11 Assignment: User Guide (50 points). For this week’s assignment, you will write a user guide.
Choose one of the following scenarios
• Your grandfather is interested in taking an online class at Rio Salado. He can use a computer and can navigate to the RioLearn website. From there, he is lost. Write a guide that not only tells him how to navigate to his class, but also informs him on how to best use the course website to be a successful student.
• Your friend wants to know how to play your favorite video game. The problem is that the game is older and you lost the user manual many years ago. You also remember that the guide got into a lot of pointless details. Your friend knows how to set up the game system; s/he just needs to know what to do once the game is on. For this guide, select a video game you play (or a board game if you prefer), and write a user guide for this audience.
• Choose a device that you are especially good at using, but that your friends or family members cannot figure out. Write a manual focused on this device. It could be as anything from setting up a VCR to understanding the data display on a hybrid car.
The goal in all cases is that your guide MUST be unique, focused on a specific audience, and developed according to the guidelines presented in this lesson, the videos, and the textbook. Please be sure to review any comments on your proposal paper and the discussions in order to craft a solid User Guide.
Your user guide must include the following:
• Table of contents
• Procedures (the instructions for use)
• Visuals with clear captions
• Who to contact for more help/where to find assistance as needed.
It should also contain at least two of the following appropriate to the audience you select:
• Warnings
• Product specifications
• Parts
• Legal notices
• Frequently asked questions
• Index
Be sure to incorporate all of the elements of technical and business writing that you have learned in this course. Your user manual should be 5-7 pages long, visually appealing, and technically accurate.
Check your work against the following grading rubric before submitting it to your instructor.
Characteristic Points
Guide contains all of the required elements (table of contents, procedures, visuals, and contact information). 25
Guide contains at least two optional elements (warnings, product specifications, parts, legal notices, frequently asked questions, index). 10
Guide is visually appealing. 10
Guide is mechanically sound/free of errors. 5
Total Points 50
When submitting your homework, be sure to include your name, the lesson number, and the writing topic at the top of your first page. Follow these Formatting Guidelines.To submit the assignment, you will attach your file within the assignment submission window at the following link: Lesson 11 Writing a User Guide.
If you need help attaching your file to the submission window, refer to Attaching Files to Assignments in RioLearn.
Summarizing Your Learning
Now that you have experienced firsthand what it is like to write a user guide, do you have a greater appreciation for the lengthy manuals that accompany products like cars and iPods? Has writing a user guide helped you to hone your organizational and planning skills in terms of writing projects? What would you do differently if you had this project to do over again?
Have You Met The Objectives For This Lesson?
Copyright © 2015 Rio Salado College. All Rights Reserved.