User Guides Tell em how to build it, operate it, fix it! Tell us where you are located! Instructions Precautionary information Reference information Getting-started information About the product Technical background. See examples of user guides. Style and Format for User Guides A user guide is a combination of many things presented in this online textbook.
As a set of instructions, a user guide should use the style and format that is presented elsewhere in this online textbook: Headings. Use headings to mark off key contents of the information so that readers can find it quickly.
See the chapter on headings for details on planning and designing headings. Use numbered and bulleted lists to help readers scan information quickly.
See the chapter on lists for details on planning and designing lists. Special notices. Use special notices such as warnings, cautions, and notes to alert readers to potential problems or emphasize special points. See the chapter on notices for details on planning and designing notices. Instructional design. In general, use the standard design of instructions; primarily, this means task-oriented headings and sections and numbered vertical lists for actual steps that readers are to perform.
See the chapter on instructions for details on planning and designing instructions. Instructions—and therefore user guides—also make abundant use of: Graphics. Show readers key components of the objects they will be working with, before and after views, and illustrations of key actions that readers must perform.
See the chapter on graphics for details on planning and designing graphics. Provide statistical information and other such details in easy-to-access table form. In user guides, tables are particularly useful whenever reference-type information must be presented. See the chapter on tables for details on planning and designing tables.
Use a consistent and standard scheme of highlighting bold, italics, alternate fonts, color, caps, and so on. See the chapter on highlighting for details on planning and designing highlighting guidelines. Components of User Guides As a book , a user guide must have some combination of the standard book-design components such as the following: Front and back covers Title page Edition notice Trademarks Disclaimers Warranties License agreements Safety notices Preface Appendixes Glossary Index Reader-comment form There is no standard combination or sequence of these elements; every company does it differently.
The most obvious are those step-by-step directions on how to assemble, operate, or troubleshoot the product. Instructions in user guide should generally be task-oriented —that is, written for specific tasks that users must perform.
Instructions should generally use vertical numbered lists for actions that must be performed in a required sequence. Similar or closely related instructions in user guides should be grouped into chapters. Precautionary information. You'll see notes, warning, caution, and even danger notices in user guides.
These represent liability concerns for the manufacturer of the product. Reference information. User guides typically contain plenty of reference information, but only up to a certain point.
For example, if there are numerous commands, a separate book for commands is necessary. Reference information in user guides is often presented in tables: columnar lists of settings, descriptions, variables, parameters, flags, and so on. Getting-started information. Some user guides will actually include brief tutorials that will help new users get acquainted with using the product. About the product. User guides also provide some description of the product, a review of its essential features or its new features.
Sometimes this information also gets put into a separate volume, if it is extensive. Typically, the volume will be called something like "Introducing New Product Sometimes, users guides will include technical explanations of how the product works, what physical or chemical principles are essential to its operation, and so on. Descriptive Examples of User Guides Consider these examples. Covers: On the front cover, you see the full book title, a version number, the company name with its logo, and warning that the book is not for retail sale.
The back cover contains advertising material—rather atypical for user guides—on the product's best features, special offers on the full version, a number to call, and the book number.
Title page: The first page inside this user guide is the title page, which includes the product name, the book title, the book edition number, the date of the edition, the company logo which includes its name , several addresses for the company, and the not-for-retail-sale warning.
The company name has a registered trademark symbol beside it; the product name has the trademark letters beside it. No trademark symbols are shown on the front or back covers. A greener approach is to omit the title page, since it is practically a duplicate of the front cover, and put the edition notice on the back of the front cover.
Edition notice: On the back of the title page is the edition notice. This edition notice includes the book title, a copyright notice, legal statements concerning copying the book, list of trademarked product names occurring in the book, and the document number. License agreement: On the next page is the software agreement, a two-page thing that outlines permitted uses of the software and related warranties. Table of contents: The TOC begins on a right-hand page numbered "i" and lists up to level of headings within the chapters.
Headers and footers: The book title is used for both the left and right footers: on the left page, the title is right-aligned; on the right page, the title is left-aligned. The page number appears opposite of both footers, and a solid ruled line is placed just above both footers. The chapter title is used for the inside header on each page; the current heading is used for the outside header on each page.
Thus, giving clear, to-the-point instructions help your customers get up to speed with your product or solve their issues with it quickly. Always using numbered lists for instructions and keep the content concise are some great practices for writing a good manual.
Adding a table of contents to your instruction manual is a must. If your instruction manual is heavy on pages, the importance of having a table of contents increases exponentially. The table of content provides navigation to the reader and helps them go to a particular topic quickly. Since customers are not looking to read your manual from start to finish and are just looking to solve a particular problem or learn about a topic, adding a table of contents helps them save time and effort.
Using a document editor that automatically creates a table of contents around headings and subheadings is a great way to go about it. Instruction manuals are well, boring. They are filled with text and are not very engaging. On top of that, visuals are processed 60, times faster in the brain than text.
Making your online manual interactive with how-to videos and audio instructions can be a great way to enhance engagement and help customers or clients effectively. Keep on reading! Therefore, always ask employees, especially those who are unfamiliar with the product or have not worked with you in creating the instruction manual, to give their honest feedback and suggestions on how to make it more effective. This is why we would like to introduce you to Bit , the smartest document collaboration tool to create instruction manuals and other digital workplace documents for free!
Bit is a new age cloud-based document collaboration tool that helps teams create, manage and track workplace documents including-. Bit helps you make sure your instruction manuals are more than just plain boring text and images. Bit will automatically turn it into a live visual web link or embed content that lives on your workplace documents! Just copy-paste the URL of your content on a blank line of the document editor and hit enter.
Bit then generates a live preview of your digital content within in your document. Imagine how rich and interactive your instruction manuals can become!
Not sure how Bit can help you write the perfect instruction manual? Bit has a minimal document editor which allows you to write your instruction manual without the distraction of unnecessary buttons and tabs. Creating an instruction manual from scratch takes a lot of time and effort. You have to research content, come up with an outline, add awesome visuals, and create an overall interactive experience for your readers.
Doing this amount of work alone can be pretty daunting and time-consuming. Thus, Bit allows you to work with your peers to get the instruction manual ready as quickly as you can. Working in teams also allows you to brainstorm ideas together and get your content and design people together in a single workplace.
Bit allows teams to collaborate together, give real-time feedback, suggest changes and get work done quicker. Most importantly, say goodbye to back and forth emails. With a persona, you make some reasonable assumptions about the characteristics of your user. This is not only useful for creating your user instructions, but it is an essential element at the start of the development of any product! As an educated industrial design engineer, this is how we started all our design assignments.
You can use the template yourself to determine who your user is. Action: Use the template to describe your user s. I am a HUGE fan of visualizing things.
So if you want to take defining your user one step further, I would suggest you visualise your user in the form of a persona. When creating a persona you are giving your user a name, age et cetera, so it becomes a real person that represents your user.
Typical problems might include: installing the product, using the product, using the product safely, maintaining the product and disposing of the product. I asked Philip to identify the problems and solutions that his user might encounter during the product lifecycle. In order to do so, I created another template for Philip. Our user manual templates are compliant with this standard.
Action: Use this template and the instructions on the first tab to identify the problems your user might have during the lifecycle of your product and present their solutions. Philip has now identified the problems a user might have with his product during its lifecycle and he has now thought of the solution to solve the problem. In other words: Philip has defined the topics for his user manual. Each topic can only be about one specific subject, has an identifiable purpose, and must be able to stand alone.
A user wants to solve one problem at a time. A topic will become a section in the user manual. It can be a chapter or a sub- paragraph. As soon as a user is looking for an answer to his problem, he will use the table of contents to find out how to navigate to that answer.
I asked Philip to structure the topics and define their place in the user manual, by assigning a certain topic to a specific chapter or sub- paragraph. You have now created the Table of Contents ToC.
The ToC is the outline of your user manual. Each topic in the user manual gets its own heading. The headings are the sub- titles that precede the actual text. They appear in the ToC, so the user can navigate to the needed information. Because the ToC entries play such an important role in helping your user find their way, and to help them skip what is NOT important, they need a bit more attention.
Basically, you should try and work with three levels of headings: first-, second- and third-level headings. The first-level heading describes what the entire chapter or section is about e. A third-level heading uses noun-phrases e. Packaging contents and Tools to be used. Meaningful Headings tab. Dependent on the market where your product is placed in or put into service, and dependent on the product group your product belongs to, specific legislation applies to your product.
These requirements also include requirements on the content of your user manual and safety instructions. In order to sell your product in a specific market, you should make sure that your user manual complies with these requirements. These two articles below will tell you how you can find out exactly which legislation applies to your product for the European and U.
Pro tip: when there is a Declaration of Conformity available already, you can find the applicable directives in there. Philip didn't need to conduct these steps, as the template he used already contained the legal content as required by the relevant directives. For his product, it means that the following information is required for the user manual for his product:. This standard has been harmonised in the EU. Compliance with harmonised standards provides a presumption of conformity with the corresponding legislation!
I have also created an IEC checklist that can be used to double check that your user manual complies with this standard. In order to create an internationally compliant user manual, you should always make sure your manual meets the EU, US and requirements. I asked him to adjust the table of contents of the template according to his own table of contents.
Without removing and mandatory elements of course Do you remember from step 4 that I asked to start the numbering of the sections with chapter 4? Once you download the user manual template doc yourself, you will see that a few standard chapters have been added, as well as some appendices. The purpose of your product, or better: the intended use, is the heart of a user manual and forms the basis of ensuring the safe and healthy use of the product.
The way the intended use is described also determines your liability and affects the further contents of the user manual. The most legislation requires you to include a description of the intended use in the user instructions. The international standard for user instructions, the IEC , provides the following definition for the intended use:.
An exhaustive range of functions or foreseen applications defined and designed by the supplier of the product. By describing the intended use you determine the safe envelope of the product. And once you have determined the intended use, you can focus on providing only those safety and user instructions for how to use the product within the given envelope.
Additionally, to the intended use, many more standards, directives and regulations also require you to include a description of the reasonably foreseeable misuse. For example, the reasonably foreseeable misuse of an aggressive detergent could be the use of it in a food processing environment. Paying too little attention to describing the reasonably foreseeable misuse will affect a company's liability. If the defectiveness of a product needs to be determined, all circumstances will be taken into account.
That includes the reasonably foreseeable use of the product. The description of the intended use determines which instructions are given in the rest of the manual. For example, if a cooling system is only used for cooling certain medications, then only these procedures need to be described.
When it could reasonably be foreseen that the cooling system may be used as a system to cool organs, this should be described in the instructions. By doing so, you, as the manufacturer, will limit your liability and you can focus on only describing how to use the system to cool medicines.
Figure 1. Reasonably foreseeable misuse? Even though the intended use has now been clearly defined, this does not mean that using a product is completely without any risks. To identify the hazards that come with the use of a product, you can conduct a risk analysis. A risk analysis can also be mandatory for certain product groups, such as low-voltage equipment, toys, machinery and equipment for use in explosive atmospheres.
Standards, like the ISO , have been developed on how to conduct a risk analysis. According to this method, there is the following hierarchy of risk-reducing measures:. This means that the user guide should warn of any residual risks related to the use of the product. This is done with safety warnings. A good safety warning describes the nature of a hazardous situation, the consequences of not avoiding a hazardous situation and the method s for avoiding it. Rotating parts.
Risk of serious injuries. Keep hands clear. Then you want to warn the user where a hazardous situation might be encountered. Do this. Do that. This is embedded safety messages. General text general text general text. In the EU, depending on the kind of product, it might be allowed to provide only the safety information in printed form and the rest of the information online.
Action: conduct a risk analysis and craft your safety messages using this template. Now I asked Philip to create all other content, such as the procedures, technical specs and legal information. Again, for most product groups there are paid templates available which might make the work easier.
These templates contain all legal texts, mandatory disposal information, copyright statements and comply with the IEC standard on user instructions. When using the template for crafting the safety messages, I asked Philip to indicate whether a safety message is a supplemental directive, or should be placed as a grouped, section or embedded safety message.
A user manual should give assistance to people by providing information about how to use a product. The crafting of meaningful headings is one of the tools that aid users in finding information.
0コメント