Create a User Manual

User manuals are written guides in either hard-copy (paper) or electronic document (PDF or XPS) format that provide instructions on how to do or use something. Although "user guides" are most often thought of in terms of computer software manuals, user manuals also accompany computers and other electronic devices such as televisions, stereos, telephone systems, and MP3 players, as well as household appliances and lawn and garden equipment. Good user manuals educate users about the product's features while teaching them how to use those features effectively and are laid out to be easily read and referred to. Following are things to consider when creating effective content for and designing the layout of a user manual.

Steps

Creating Appropriate User Documentation

  1. Define who your user is. To write a successful user manual, you need to develop a profile of your user, either formally, by creating a written profile, or informally, by taking the time to make reasonable assumptions about your user's characteristics. Such a profile is useful when you're part of a team writing the user documentation and can also be helpful in taking the product itself from concept to final form. Things to think about when forming a user profile include:
    • Where users will use the user guide, such as at home, in the office, at a remote job site, or in the car. This may determine not only the content, but the style the user manual takes.
    • How users will use the user guide. If the manual is one they will consult only infrequently or to look up information, it should primarily take the form of a reference document. If it is something users will consult frequently in the beginning, the reference section should be accompanied by a "Getting Started" section and instructions on the most common tasks the product will be used for.
    • How much experience users have with the product or others like it. If your product is new or significantly different from similar products, you'll need to include an explanation of how it differs from other products as well as instructions on how to get started. If the product deals with something users often have trouble with, such as many computer applications, you'll need to provide appropriate information and detail in an understandable fashion.
  2. Write to your user's needs in a way the user can understand. Unless the user has a technical background, it is probably best to avoid highly technical language in favor of clear, simple explanations. The text should also be organized in a way that mimics the way users think; listing product features grouped by function often makes more sense than simply those used most often.
    • Sometimes there is no getting around using technical terms, such as for a graph-creating software application that includes Fibonacci charts along with more common pie and bar graphs. In such a case, it is helpful to define the term and provide some background, such as an explanation of what Fibonacci charts are and their use in financial analysis.
  3. Explain the problem the user is trying to solve, then present the solution to it. Offering a feature as the solution to a general problem works fine when marketing the product, but once the user has the product, he or she needs to figure out how to put it to use. Identify specific problems the user will face, state them in the user guide, and then follow with instructions to solve them.
    • If the problem is a complex one, break it down into smaller parts. List each part with the instructions on how to solve or cope with it, and then follow with each subsequent part in succession. Breaking information down this way is called "chunking."

User Manual Components

  1. Include the appropriate cover and title pages. You'll need a front cover for any user guide that's more than a reference card and a title page for any manual that covers more than a folded sheet of paper (4 or more pages in length).
    • If the manual is copyrighted, a copyright notice goes on both the front cover and title page.
    • If there are terms and conditions for using the manual and product associated with it, place them on the inside front cover.
  2. Put references to related documents in the preface. If the user documentation is more than 1 manual, make reference to the other documents, with the correct version numbers, here. The preface is also where to put a "How to Use This Guide" section if there is one.
  3. Include a table of contents if the manual exceeds 10 pages.
  4. Put instructions/procedures and reference materials in the body of the manual. In most cases, procedures and reference materials should each have their own sections, although you can tell the user to refer to specific content in one section from the other. This way, the user can find the information he or she is looking for faster.
    • Procedures should be written in a consistent structure throughout the instruction section of the manual. Begin with an overview of the task, then describe what the user has to do and what result he or she should see. Steps should be numbered and begin with action verbs, as the steps in each section of this article are written.
    • Reference materials can include lists of options, troubleshooting tips, and frequently asked questions. Glossaries and indexes can be added near the end of the manual, although a list of frequently used terms can appear at the front. The index can be omitted if the manual runs less than 20 pages.
  5. Use graphic images as needed to support the text. Graphic images, or screenshots, can illustrate certain points in the manual better than text, particularly in complex procedures where users need to have visual confirmation that they're performing the steps correctly. Graphic images can be produced using computer-aided drafting (CAD) or graphic editing software, digital cameras and photo-editing software, or in the case of screenshots, either your computer's built-in screen capture ability or a graphics program with screen capture capability.
    • Once you create a graphic image, save it in as compressed a format as your word processing or desktop publishing program will allow you to use. You'll also want to reduce the physical size of your image to something that will fit more easily on the page while still providing sufficient detail for the user. (If necessary, you may need to cut the original image into parts and show the relevant parts along with the supporting text.)
    • If you're using multiple graphic images in procedures, make them a consistent size, either in the same dimensions of length and width or in the same proportional reduction from their original size. This will make the images more attractive to the user. Likewise, when creating screenshots from a computer, make sure the computer is displaying a standard color scheme when capturing images if the user manual will display the screenshots in color.
    • Although graphic editing programs such as Photoshop and Paint Shop Pro offer decent screen capture capabilities, dedicated screen capture programs such as SnagIt also feature the ability to easily modify, catalog, and annotate screen captures.

Designing a Readable User Manual

  1. Choose a few readable fonts. Although computers can support a number of different fonts, the goal of a user manual is to be an easily readable. Choosing only a small number of fonts that look good together is the best way to achieve this goal. Fonts can be broken down into 2 types: serif and sans serif fonts.
    • Serif fonts feature small embellishment lines at the ends of the main strokes that form the letter. Serif fonts include such fonts as Times New Roman, Baskerville, and Book Antiqua. Serif fonts work best for large chunks of text displayed in 10 to 12 point size in the main body of a printed user manual.
    • Sans serif fonts display only the strokes that form the letters without embellishment. Sans serif fonts include such fonts as Arial, Calibri, and Century Gothic. Sans serif fonts can be used for large chunks of text in sizes from 8 to 10 point in a PDF or Web-based manual, although the lack of serifs makes sentences displayed in sizes 12 point or larger harder to read. They can, however, be used effectively in larger sizes to display titles and headings, and they're also great in the smaller sizes for footnotes and numbers in columns and tables.
    • You should generally choose plain fonts such as Arial or Times New Roman for your user manual, although you may want to use a decorative font for pull quotes or for titles if you're writing a user manual for a video game with a fantasy or science fiction setting. (In the case of pull quotes, you can often get by with one of the plain fonts and display the pull quote in italics.)
    • Once you have decided on the fonts you want to use, create a sample page to verify that your fonts go together well on paper. You'll also want to show this sample to whoever has approval over the manual's appearance before you proceed further with writing it.
  2. Give some thought to the layout. Once you've chosen your user manual's fonts, you need to decide where everything goes on the pages.
    • Generally, you'll want to put the manual's title or the chapter title in the header or footer, possibly using the manual title on the left-hand page and the chapter title on the right-hand page. You'll want to have the page numbers in the header or footer as well, either to the outside (header or footer) or in the center (footer only). You may want to have the first page of each section or chapter differ from the other pages by placing its page number in the center of the footer and subsequent pages in the outside corner of the header.
    • You may want to have callout text in colored or shaded boxes to separate it from the rest of the text. Be sure to choose a color or level of shading that doesn't overwhelm the text.
    • Allow reasonably ample margins on all sides, with extra space on the edges that will be bound together.
  3. Consider the type of binding for the user manual. If your user manual runs more than 4 pages, the pages will need to be bound together in some way. Although internal documents may be stapled together at the corner, external user manuals that ship with a product are usually bound in one of 3 ways:
    • Side-stapling is appropriate for manuals composed of folded 8.5 x 11-inch (21 x 27.5-cm), 8.5 x 14-inch (21 x 35-cm), or 11 x 17-inch (27.5 x 42.5-cm) sheets of paper. Most inexpensive manuals of 48 pages or fewer are bound this way.
    • Saddle-stitching is more commonly used for third-party reference guides than for user manuals that ship with products other than automobiles, although some lengthier user guides are bound this way. (Paint Shop Pro originally shipped with a saddle-stitch bound user guide when it was produced by JASC Software.)
    • Spiral binding is appropriate for user guides designed to be used in more rugged settings, such as the outdoors, where side-stapled or saddle-stitched manuals would fall apart. Some spiral-bound manuals may also have laminated pages to keep them from being ruined if the manual gets wet or muddy.
  4. Build a template document for your manual. Many word processing and desktop publishing programs offer you the ability to create a template document for your user manual, so that as you type, the text will automatically display in the font you selected for the portion of the manual you're working on. (This article, in fact, was written initially using a Microsoft Word template.) Most of these programs also include a set of pre-defined templates that you can modify for your needs, instead of creating the template from scratch.
    • Word-processing and desktop publishing programs also offer the ability to create "styles," preset font and point-size formats for headers, footers, headings, and body text. You can select one of the defined style names (e.g., "Heading1," "Normal," "Quote") or create your own style with its own name. As much as possible, follow the conventions for established style names if you have multiple styles for the same class of text. (For example, Microsoft Word labels text styles for headings as "Heading1," "Heading2," etc. for headings from the main heading through several levels of subheads.) Try to create all the styles you'll need upfront so you don't have to stop and create them during the actual writing process.



Tips

  • Make use of field codes or text variables where possible. You can assign them values, such as the name of a product, the manual or a chapter title, and place inside your document in place of typing the actual text. When you preview or print the manual, the text will fill in for the variable. If the product's name changes, or if you change the name of the manual or a chapter, it will be easier to change the information by changing the value of the text variable than by doing a search and replace of the document.

Things You'll Need

  • Word processing or desktop publishing program
  • Graphic editing or screen capture program

Sources and Citations

Retrieved from "https://kipkis.com/index.php?title=Create_a_User_Manual&oldid=352600"