Planning Your User Manual
Do an audience analysis. The user manual should be written for the audience -- those who will be purchasing your product or service and reading the user manual. An audience analysis will tell you who your main or target audience will be and will guide your writing. Talk to people who will use your device. Offer test users prototypes of the device and a draft of the user manual under controlled conditions. Solicit these test users’ feedback about things that are not obvious or confusing in the user directions and incorporate changes into your user manual based on this feedback. You can never please your entire audience; write the manual to suit the target or largest audience. Think about the audience’s age, health (do they have illnesses, learning impairments, or disabilities?), and educational level to determine the best approach to writing the user guide.
Coordinate the design of the user manual. If you were part of the team that helped design and develop the device or product, it might be hard to look at the product objectively in order to explain its operation. You might, therefore, want to solicit the advice of a writer (preferably one with experience in writing instructions) and graphic designer in order to help you draft the user manual. You could choose these individuals from an outside consultancy or from your own company or organization.
Do a task analysis. A task analysis is the process of identifying and organizing the steps needed to use the device. A thorough task analysis will identify the materials and equipment (such as batteries, medications, or other user-provided products) needed for each step, as well as the actions, errors, and troubleshooting advice that each step might require. If you have a product that can perform many different tasks or sub-tasks, you will need to perform a task analysis on each task. For instance, in a car, you can honk the horn, strap yourself in, and turn your headlights on or off. Create a task analysis for each of these as needed.
Ensure your product complies with labeling and marketing clearance requirements. These requirements ensure that products are produced with user safety in mind, and will limit user exposure to dangerous conditions such as radiation and electrocution. Advertisements must demonstrate clearly what the purpose and basic operational guidelines of a product are, and you should use these sources when writing your user manual. For the user manual of a product to be effective, it needs to be written in concert with labels affixed directly to the product. Ensure your device is legally licensed for sale before writing instruction manual.
Decide on your manual’s layout. There are several important ways you can streamline your manual. You should place a bold heading at the start of each section with each word capitalized. For instance, “Setting Up Your Device,” “Operating Your Device,” and “Troubleshooting” could all be bold section headings. Another way to streamline your manual is to use two columns, one on the right with text and the other just to the left of the text with bullet points, numbers, or small icons like warning signs or red exclamation marks. Your manual might be mostly images with some text beneath each image to explain the device, or it could be primarily text with only a few accompanying images. You could also use a flow chart to provide the user with directions. Think about your product and how each method might be of use when writing your user manual. However, avoid mixing different layouts within a manual. Choose one and stick with it.
Including Essential Information
Organize the manual logically. The user manual should proceed in a way that the user will find most beneficial. Split the manual into chapters or sections that make sense for the product's use, and include a table of contents toward the front of the manual so each section can be found quickly. A table of contents is especially necessary for longer manuals. A glossary or index is needed when there are many terms to explain that your audience may not be familiar with. However, glossaries are not recommended; the best choice is to explain confusing terms in the text of the manual itself. If you choose to include a glossary, place it in front of the manual, just after the table of contents. A list of tables or figures is only necessary if there are more than a few tables or figures in the manual. An appendix is needed for things that should be explained but cannot be explained at another point in the manual because it would disturb the flow and focus.
Include necessary warnings. The general warnings or cautionary information should provide information about potential threats improper use of the product could incur, including death or serious injury. These warnings should be placed in the very front of the manual after the cover page so that the user sees them first. Specific warnings should also be included in the text of the user manual just after or just before a potentially hazardous step is suggested. For instance, a general warning for an electric device might be to avoid using it during rain. A specific direction might be to ensure that your hands and the device are both dry before plugging the device in. Include graphics (such as a skull and crossbones) or different-colored text (like red text) to differentiate the warning from the rest of the directions in the user manual and draw users’ attention to it. You could explain the benefits of following the manual instead of working independently.
Describe the device. Your description should include both a written explanation as to the device’s purpose and a small graphic depicting what the device looks like. The graphic should properly label and name all the switches, knobs, and attachable parts that the device includes.
Include setup instructions. The setup section should include basic information about how to prepare to use the product or device. If the device cannot be constructed or set up by a home user, state this fact plainly in a bold header at the top of the setup section. You should also include: A parts list Unpacking instructions Warnings related to setup Results of an improper setup Who to call in case they encounter difficulty in setting up
Provide information about operation. This section is the main portion of the user manual and should provide concrete, detailed information on how to use the device. Begin with basic preparation for using the device, such as plugging it in or washing your hands. Move on to logical, numbered steps that describe how the device should be used, as well as feedback (for instance, “You’ll hear a click...”) the user can expect when using the device appropriately. At the end of this section, users should be referred to the troubleshooting section in order to solve problems that can’t be quickly explained. Include graphics where necessary. Some steps are best explained with images as well as words. Think about using photographs or illustrations in your user manual. In this section, as in every section, be sure to include relevant safety warnings about improper use or operation. For instance, you might warn users of a chainsaw not to drink alcohol or use the chainsaw while on certain medications. If you think users would benefit, consider including links to online videos that demonstrate proper use and operation of the device. You could include these videos either at the beginning of this section, or (in the case of videos that illustrate only one step) at the end of each step. Try to keep your instructions as simple as possible. If your manual gets too complicated, you might lose people along the way.
Include a product summary at the end. The summary should go at the end of the manual, just before the index, in order to provide basic steps of operation. This should be a simplified, stripped-down version of the operational information section, and should be no more than one page. Summarize how to use the device or product. Include basic warnings, numbered step explaining how to use the product, and phone numbers or email addresses that direct users to help. If you expect the user will remove the summary sheet or need to consult it frequently, you could print it on a removal laminated card, or thick card stock to make it easier for the user to carry with them and reference. Alternatively, include a summary sheet directly on the product so that users can reference it quickly and easily.
Describing Product Care
Explain how to clean the device. If your device or product requires cleaning, explain how to do so. Be sure to enumerate the cleaning supplies needed. Inform the reader of how often they should clean. Then, just as you would in any other section of the user manual, include numbered step-by-step instructions as to how cleaning should proceed. If cleaning requires some disassembly of the product, or removal of a certain part or parts, be sure to include details on how to disassemble. Include a warning about the results of failing to clean the device will be. For instance, you might say, “Failure to clean will result in a below optimal performance.”
Tell the user how to perform basic maintenance. If the product or device can be serviced by the user to correct performance issues, include numbered directions as to how the user can do so. For instance, if the batteries need to be changed after every 300 hours of use, include directions on how to check whether the batteries need to be changed, how to remove the dead batteries, and how to insert the new batteries. If there are some maintenance tasks that can only be performed by a certified technician, divide the maintenance portion of the manual into two sections.
Discuss storage options. The user manual should, if necessary, explain how to store the product or device properly. You should also include information about why storage is necessary, and what the results of improper storage are. For instance, you might write: “Store the product in a cool, dry place. Improper storage could shorten the life of your product due to the buildup of moisture.” "Do not expose product to heat or store at temperatures above 120 °F (49 °C). Doing so may lead to combustion."
Include troubleshooting information. You might organize this section as a list of common problems and their solutions. Group similar problems together under a logical heading. This way, users can find specific problems quickly. For instance, if there are several problems with the computer displaying a blue screen, list them together under a sub-heading like “Common Screen Problems.” You should also include a phone number and/or email for customer service in this section.
Writing a Readable Manual
Read other user manuals. Before writing a manual for your own product, look at other effective user manuals. Pay attention to the structure, word choice, and sentence style. Major brands like Apple, Google, and Microsoft produce strong, effective user manuals that can help you produce a more thoughtfully written user manual. Don't just read any user manuals. Read the manuals for similar products that you are selling. For example, if you're selling baby products, read baby manuals, not tech.
Select your standards. Standardizing spelling, word choice, and phrasing will make the user manual more user-friendly. The Chicago Manual of Style and the Microsoft Manual of Style might also be useful style guides when writing your user manual; consult both to see if one will work for your manual. For instance, instead of using both “on/off switch” and “power switch” in your user manual, choose one or the other term and stick with it.
Use active voice. Active voice is a perspective in writing that explains things from the user’s perspective. It is easier to understand than its alternative, passive voice, in which the subject is undefined. Try the Hemingway App (www.hemmingwayapp.com) to identify passive passages in your writing. Examine these two sentences, the first active and the other passive, for examples of each: You should open the package slowly and carefully. The package should be opened slowly and carefully.
Write numbered instructions. Numerically ordered instructions will help the reader stay more focused on the process of using, connecting, or building the product in question. Instead of writing a long, rambling paragraph, or a series of un-numbered paragraphs, write your user manual with simple, explicit steps, each numbered clearly.
Start each step with an imperative. An imperative is an action-oriented verb. By starting each step with a verb, you will clue the reader in to the action required to complete the step. For instance, depending on the product you’re writing about, you might begin your steps with imperatives like “Connect,” “Attach,” or “Slide.” Do not begin your steps with a system response, however. For example, if the screen will turn blue and blink, don't start the step with: “The screen will blink and turn blue.” Try: "Press and hold the home key. The screen will blink and turn blue."
Decide what kind of vocabulary you’ll use. If you’re writing a yo-yo user manual, your audience will be mostly young children. Use simple words and vocabulary in order to explain how the yo-yo works. If you’re writing a user manual for a scanning electron microscope, your audience will be highly trained scientists who can understand highly detailed information, so don’t shrink from using specialized vocabulary or nuanced explanations. In general, try to avoid jargon and technical language. To be effective to the broadest array of users, try to write at a sixth to seventh grade reading level.
Ensure your translations are accurate if you are shipping a product overseas. Hire a translator to translate your user manual into the native language of the country that you are shipping your product to. Alternatively, use an online translating app, but ask a native speaker read over and edit the translation for errors. If there are multiple language groups represented in your audience, include translations of the user manual in each relevant language. The translator should be familiar with the product, as there may be different words for specific terms in the target language that not are word-for-word translations.
Keep your writing brief. Instead of a few long paragraphs, use many short paragraphs. Look for logical breaks in each section and put useful information into one or two-sentence chunks. The same applies at the sentence level. Keep your sentences short and simple, rather than long and rambling. If a step is starting to get too long, break it up into smaller steps. This won't cause the word-count to go down, but the line breaks will make it easier to read.
Proofread the manual. A manual can lose credibility due to grammar and spelling mistakes. Have a coworker or technical writer edit and proofread the manual as well. In addition to spelling and grammar, a proofreader should look for: Passive voice Ambiguous or confusing language Complicated sentence structure Overly long paragraphs
Comments
0 comment