You are searching for keyword: {{ keyword }}

User Manual Template Case Study: How A Hardware Startup Created A Legally Compliant User Manual In One Week

Ferry Vermeulen Tools & Efficiency

Today I’m going to show you how one entrepreneur used the User Manual Template to create his own compliant, user-friendly and appealing user manual.

And he did this without any knowledge of technical writing.

Philip is a Swedish 34-year business owner and inventor of the ISOVOX2, a portable vocal studio.

Like many startup companies, Philip needs to be very careful about where he spends his money. Most time and money needs to be spent on product development and setting up the sales channels.

His product needs a user guide, however. He knows that there are some legal requirements for the content of the manual and he wants a well designed and user-friendly instructional manual that contributes to a good customer experience.

As he has some resources in-house, he does not want to outsource the full development of the manual. I decided to walk him through the entire process and develop an instruction manual template for him. Here’s what happened.

In a few emails I told him exactly what to do, step by step. The results are as follows: 

  • A manual that enables 1st run of product to ship on time with no delays and passing customs without any problems.
  • Clear instructions on how to install and use the product
  • A complete list of safety instructions
  • A manual that meets all legal requirements
  • A design that meets his company's brand identity
  • A manual that meets the legal IEC EN 82079 standard for User Instructions

These are the steps we followed:

Step 1 Getting General Knowledge on How to Create User Manuals

Before actually using the User Manual Template and the other tools that I developed for Philip, I wanted to make sure we have the same starting point. I provided him with some general information about user instructions and with some good examples of existing user guides.

I have listed this information below.

Definition of a User Manual

A user guide is a technical communication document intended to give assistance to people on how to use a product.

A good user guide assists users on how to use a product safely, healthily and effectively.

Other names, or other forms of a user guide, might be:

  • User manual
  • Technical documentation
  • Instruction manual
  • Operational manual
  • Training manual
  • Quick Start Guide
  • Installation manual
  • Maintenance manual
  • Software manual

Besides the primary goal of a user manual (assist a user), secondary goals could be creating a better user experience and meeting legal requirements.

A user guide consists of textual visual information (illustrations, screenshots, tables etc.) to assist the user in completing specific tasks.

The user plays the central role when drawing up a user manual. A well-drafted user guide only provides that information that is relevant for the intended user of the product.

The user manual should contain both procedural information (step-by-step instructions) and conceptual information (information the user needs in order to understand procedural information).

A good user manual is concise and uses jargon-free language. A good user guide should answer HOW and WHAT questions. They should contain information about what happens if a task is not done correctly.

In some cases, a product is intended to be used by different types of users. Typical user types are the end-user, installer, maintenance engineer and operator. Each user type needs a different approach in terms of language to be used, the tone of voice and provided conceptual information.

What Information Should Be in a User Guide

Different kind of products need a user guide. A product can be a system, tool, device, an instrument, a piece of software or an app. Depending on the type of product, a user guide might include things as:

  • Product name
  • Model or type number
  • Intended use
  • Features/accessories
  • Description of the main product elements
  • Description of the user interface
  • Safety warnings
  • Installation instructions
  • Description of how to use/operate the product
  • Troubleshooting section and instructions on how to solve problems
  • Maintenance information
  • Repair information
  • Information on disposal of the product and packaging
  • Technical specifications
  • Table of content
  • Index
  • Glossary
  • Warranty information
  • Contact details

User Guide Template

The main tool that I developed in order to help Philip draw up his user manual is the User Manual Template. The template contains all the information and more from the list above.

The User Manual Template can be used for creating your manual for your system, tool, device, instrument, or for creating an installation manual, software manual, operational manual, maintenance manual or training manual.

Formats of a User Guide

User manuals can be provided in either a paper format or as an electronic document (PDF or placed online or on-device in HTML).

User manuals can be created using a variety of tools. Each tool has its own advantages and disadvantages. I will mention the most common tools below:

  Advantages Disadvantages
Word Easy to learn
User guide template can be set up easily
Less suitable for large documents
No reuse of content possible
Indesign High degree of design freedom Content changes may require many extra DTP hours
CMS (technical authoring & publishing solutions) Reuse of content
All in one solution
Omni-platform publications
Contains default user guide templates
High learning curve 

User Guide Example

While drafting a user manual with help of the User Manual Template, it can be handy to have some good examples. Through the following links you can download a user manual sample for documentation:

 

Step 2 Identify the User(s) of Your User Guide

Ok, so now Philip has some basic knowledge about user manuals. Let’s dive into the details and actions.

When you want to write a manual that helps your user to solve problems, you first need to define who your user is. This can be done by creating a user profile, also named a persona.

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.

When checking the ISOVOX website, I didn’t even find a clear description of their intended users. That’s why I asked Philip to define his users and answer questions like:

  • Who is the user of your product?
  • Is the product used professionally or mainly privately?
  • What other technical experiences do they have? What describes the user?

I have created a template that contains the questions. I asked Philip to fill out the template.

You can use the template yourself to determine who your user is. Please note that the second tab also contains Philip’s answers, so you have an example of how the sheet could be used.

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.

I did this for Philip. This is the result:

Action: Create a visualization of your user

If you want to know more about defining your audience and creating personas:

https://www.nngroup.com/articles/persona/
http://www.astauthors.co.uk/aboutast/articles/determiningyouraudience.php
https://www.smashingmagazine.com/2014/08/a-closer-look-at-personas-part-1/
https://www.prismnet.com/~hcexres/textbook/aud.html

Step 3 Creating topics for your user’s problems

Start with identifying the problems that your user(s) might encounter during the lifecycle of the product and that s/he wants to solve. Typical problems might include: installing the product, using the product, using the product safely, maintaining the product and disposing of the product.

If the problem is too complex, you could break it down into chunks.

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. In the left column of the Lifecycle tab, the stages of a product’s lifecycle are mentioned. These are derived from the international standard for user instructions, the IEC 82079.

On the Lifecycle [ISOVOX] tab you see how Philip adjusted the lifecycle to his own product.

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.

If you want to know more about defining your user’s problems and creating topics:

Step 4 Define the structure of the user guide

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 guide. Each topic can only be about one specific subject, has an identifiable purpose, and must be able to stand alone.

A topic should give the answer to only one user’s question. A user wants to solve one problem at a time. When a user has solved the problem, he/she will go and solve the next problem.

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 guide, by assigning a certain topic to a specific chapter or (sub-)paragraph. The result can be seen on the ToC [ISOVOX] tab.

Action: To define the structure of your user guide:

  1. Copy the content from the Lifecycle [product name] tab to the ToC [product name] tab
  2. On the ToC [product name] tab, replace product name with your own product name.
  3. Add a column to the left. Name it ‘Section’.
  4. If applicable, organize your sections logically.
  5. Determine what topics will become chapters by adding chapter numbers. Start numbering PREPARATION PRODUCT FOR USE with number 4. We will add some more chapters in the next step.
  6. Determine what topics will become paragraphs by adding the section numbers.
  7. Determine what topics will become sub-paragraphs by adding the subsection numbers.

You have now created the Table of Contents (ToC). The ToC is the outline of your user manual. Later we will add some more topics/sections, like the Introduction, Safety Information etc., so don’t worry about adding that now.

Step 5 Create meaningful headings

Each topic in the user guide 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.

So, Philip has just created the (sub-)titles for his topics.

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.g. INSTALLATION OF THE PRODUCT). The second-level headings should use the ‘how what’ style of phrasing (e.g. How to Assemble the Product and How to Do the Electrical Installation). A third-level heading uses noun-phrases (e.g. Packaging contents and Tools to be used).

I asked Philip to redirect his headings and to take notice of the following general guidelines:

  • Use the structure as shown above for the first, second and third level heading.
  • Make sure the headings are self-explanatory. The heading Making Pancakes is much more user-oriented than Using the MagicCook5000.
  • Make sure that the heading covers the full topic. If the section covers the maintenance and repair of a product, the heading Maintenance would be incomplete.
  • If possible, try to omit articles at the beginning of headings

Action: Write new headings for your ToC entries.

Philips’s ToC with meaningful headings can be found on the ToC w. Meaningful Headings tab.

Step 6 Determine the Legal Content

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.

In general, the legislation requires that your product is ‘safe’ and therefore gives general safety requirements your product should meet.

These requirements also include requirements on the content of your user guide 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 will tell you how you can find out exactly which legislation applies to your product for the European and U.S. market and what the requirements are for your user guide:

By following the steps as described in these articles, Philip found out that the following information is required for the user guide for his product:

EU (relevant directives: LVD, EMC, RoHS, WEEE, REACH):

  • The user manual should be translated to the language(s) of the country where the product is sold.
  • The user manual should describe the intended use of the product.
  • The user manual should describe the reasonably foreseen unintended use of the product.
  • If applicable, non-compliance in residential areas should be mentioned.
  • The type, batch or serial number or other element allowing the product’s identification should be mentioned on the product. If the product is too small this can be placed in the user manual.
  • The name, registered trade name or registered trademark and the postal address should be mentioned on the product. If the product is too small this can be placed in the user manual.
  • A risk analysis should be conducted to determine the residual risks related to the use of the product. Safety information shall be provided in order to inform the user of measures to be taken.
  • WEEE information shall be included
  • Information on packaging waste shall be included.

US (relevant standard: ANSI Z535.6)

  • The user guide should contain safety messages in order to warn against any product risks related to the use of the product.
  • In the safety messages, the words “may”, “shall” and “should” should be used with the appropriate meaning:
      • May: This word is understood to be permissive.
      • Shall: This word is understood to be mandatory.
      • Should: This word is understood to be advisory. 
  • Depending on the risk level, the safety messages should contain the correct signal word (DANGER, WARNING, CAUTION or NOTICE)
  • The safety messages should be placed in the user manual where they warn the user best: grouped in a separate chapter, in the first part of the specific section to which they apply or embedded in the instruction where a risk might occur.

Besides this legislation, there also is an international standard for user manuals, the IEC 82079-1:2012. This standard has been harmonised in the EU. Compliance with harmonised standards provides a presumption of conformity with the corresponding legislation!

I have created this IEC 82079 checklist that can be used to ensure your user manual complies with this standard.

I asked Philip to have a close look at this checklist and, if applicable, to update his ToC with the requirements of the 82079 standard.

In order to create an internationally compliant user guide, you should make sure your manual meets the EU, US and 80279 requirements.

Action: To determine the legal requirements on your user guide:

  1. Follow steps 1-2 from the EU compliance and/or steps 1-6 from the US compliance articles to determine the legal framework for your instructions.
  2. Study the checklist to ensure your manual complies with the 82079 standard.

Step 7 Download and Prepare the User Guide Template

Now Philip can start the actual creation of his user manual. Again, I have made things VERY easy for him.

I have created a user guide template that I asked him to adjust by adding the requirements from the legal research and by adjusting the table of contents according to his own table of contents.

User Manual Template

Do you remember from step 4 that I asked to start the numbering of the sections with chapter 4? Once you download the user guide template doc yourself, you will see that a few standard chapters have been added, as well as some appendices.

Action: To adjust the user manual template:

If you want to work with the free template:

  1. Download the free user manual template Word 2013 or 2007
  2. Change the section headings according to your own ToC. Notice!  Do not adjust the Table of Contents. The table of contents can be updated automatically once you have adjusted the section headings.
  3. Add the mandatory content as determined in step 6 of your manual.
  4. If applicable, modify sections 1-3 and the appendices according to your own needs.

Step 8 Create the Content for Your User Manual


Write the Intended Use

The purpose of your product, or better: the intended use, is the heart of a user guide 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.

Most legislation requires you to include a description of the intended use in the user instructions.

The international standard for user instructions, the IEC 82079-1, provides the following definition for the intended use:

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.

Product liability laws/regulation hold a manufacturer liable for a defective product. 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.

Action: write the intended use and the reasonably foreseeable misuse of your product.

Intended Use
Figure 1. Reasonably foreseeable misuse?

Write the safety warnings based on the risk analysis

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 12100, have been developed on how to conduct a risk analysis. The ISO 12100 also gives a method for taking mitigation measures: the Three-Step Method. According to this method, there is the following hierarchy of risk-reducing measures:

  1. Inherently safe design measures
  2. Safeguarding and complementary protective measures
  3. Information for use

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.

To indicate the degree of hazard that may be encountered by the user, the signal words “Danger”, “Warning” and “Caution” should be used.

Have a look at the following safety messages:

WARNING! Rotating parts. Risk of serious injuries. Keep hands clear. Lockout/Tagout before servicing.

Then you want to warn the user where a hazardous situation might be encountered. The ANSI Z535.6 standard describes the following locations in the user guide where this could be:

  • Grouped in a separate chapter.
  • In the first part of the specific section:
    Section safety message
  • Embedded in a procedure:

1. Do this.
2. Do that. WARNING! This is embedded safety messages. General text general text general text.
3. Do this.

  • In the Preface any supplemental directives can be placed, such as Read all instructions before use or Keep these instructions for future reference can be placed in the introduction of a user guide.

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.

In order to help Philip create and place a safety message, I have created this template.

Action: conduct a risk analysis and craft your safety messages using this template.

Create all other content

Now I asked Philip to create all other content, such as the procedures, technical specs and legal information.

I gave the following tips: 

  • Exclude unnecessary material to avoid information overload (for example sales promotion, extensive repetition etc).
  • Make sure terms are familiar to the user, technical features and terms are well explained and use terms consistently.
  • Describe any prerequisites that should be met before the actual instructions start. This may also be describing special tools or space for maintenance and repair.
  • Provide conceptual information when information is necessary for adequate understanding and execution of tasks.
  • Always write topic based.
  • Use a bold typeface for all product elements.
  • Indicate when you want to add an image for better understanding later.
  • Make sure words and phrases are not too complicated or over-sophisticated.
  • Use simple/standardized and short phrases: one sentence-one command.
  • Don’t put too much information into one sentence.
  • Use the direct active voice and assertive commands.
  • Use words like nouns and verbs consistently to avoid ambiguity.
  • To write better instructions, use the Principles of Minimalism in Technical Communication and Simplified Technical English.

Action: create all other content for your user manual.

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 82079 standard on user instructions.

Place the safety warnings in the right position

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.

Now all text has been created, the safety messages can be placed in the right place.

Action: place all safety messages in the right location in the user manual.

Step 9 Add Navigation

A user manual should give assistance to people by providing information about how to use a product. Finding the right information that solves the user’s problem should take as little time as possible.

The crafting of meaningful headings is one of the tools that aid users in finding information. However, there are several other tools to help the user finding the information he/she wants, such as:

  • Table of contents
  • Page numbering
  • Index

I asked Philip to update the table of contents and add page numbering and an index.

Action: Add or update your table of contents, page numbering and index.

Step 10 Have Your User Guide Reviewed

Philip has now created the draft version of his user manual, using the user guide template. We call this version the textual content design.

As Philip has a business partner and a developer with in-depth technical product knowledge, I asked Philip to let them review the work so far.

Both his business partner and the developer provided feedback. Philip used this feedback to optimize the user guide.

Action: Send the draft version of the user manual to anyone within your team who might be able to deliver feedback. Ask them to combine all feedback into one document before sending it back to you. This stimulates discussion of your team members and prevents disagreement at a later stage.

Step 11 Create the images

Once the user guide has been reviewed and optimized, the texts are more or less definite. This means that any images can now be created and added to the content.

The reason to wait until the texts are ready is that creating or editing images can be time-consuming. As images should support, replace, or augment text, you want to wait to create them until the texts are final.

Images in user manuals may include illustrations, photos, screenshots, tables, diagrams and schematics.

There are many great tools that can help you create your images, such as:

Technical illustrations 

I advised Philip not to use photos as a cheap alternative for illustrations. Often, photos are not as informative because they contain too much information. Besides that, photos can make a user guide look messy.

For that reason, Philip used Google Sketchup to create his illustrations.

Action: Create the images for your user manual.

If you want to know more about creating images:

Snagit

Step 12 Final Check

Before we start making it look nice and translate the content, we want to be sure that the content is complete.

In order to do so, I asked Philip to use this checklist.

Action: l make sure that your user manual complies with all relevant requirements from the IEC 82079-1:2012 by using this checklist.

Step 13 Design Your User Guide

A well designed manual contributes to a better brand and user experience.

You can adjust the User Guide Template in MS Word by adding a company logo and adjust the font, colours et cetera, but that might have limitations.

When you know how to work with Adobe Indesign, or are willing to learn to work with it, this will offer you much greater design possibilities.

I created this template in Indesign and asked Philip to adjust it to match his brand identity.

 

Action: Adjust the User Guide Template to fit your brand identity, or download the InDesign template and adjust it.

Step 14 DTP Works

DTP stands for Desktop Publishing and Wikipedia describes it as ‘the creation of documents using page layout skills on a personal computer primarily for print’.

Philip now has both the content of his user manual (Word file) and the template (InDesign file). The content needs to be put into the InDesign template. This is called Desktop Publishing.

Action: place the content from your Word file into the Indesign template. If you decided not to use the InDesign template but stuck to the Word file, then you can skip this step.

Step 15 Translations

Depending on the market in which you are going to sell your product, you might need to translate the user manual.

Some general tips:

  • Look for a translator with similar experience. This could be experience in translating technical content, with similar products or with translating user manuals.
  • If you need to translate to several languages, working with a translation agency might save you lots of time.
  • Ask the translator or agency about their quality procedures and who is going to revise the text after translation.
  • As you know your product best and who your audience is, it might be a good idea to provide the translator or agency a glossary or a list with the terminology that you want to use.
  • Look for a translator who can work directly in your Word or InDesign file or find an agency that can do the DTP works as well. Alternatively, you can do this yourself, of course.

As Philip will sell his product in both the US and EU, he decided to work with an agency.

Action: Find a translator or agency that fits your needs and have your user manual translated.

Step 16 Publish Your User Guide(s)

In general, a user guide should be available in a format that is easy accessible to the user. That can be printed, or used online or on-device.

As a user wants information at the moment he/she needs it, and thus does not think in channels, the best approach would be to provide the instructions omni-platform.

In the European Union, for some product groups, it is still restricted to provide the user guide printed with the product.

However, as of April 2016, the instructions of many product groups may be delivered in a different format rather than in print. There is one exception, however.

Safety information shall still be delivered in paper form along with the product. Besides that, upon request from a consumer, a paper user manual should be made available to the consumer.

Philip decided to the following:

  • He provides a printed full manual with the product, including the safety instructions.
  • He created a separate quick start guide to be provided with the product as well.
  • He placed a pdf version of the full manual online.
  • He will create an online-help section on his website with the HTML version of the user manual. Here he can add videos as well. And by optimizing the HTML version for search engines he makes it easier for his user to find information for his user

Conclusion

That’s all there is to it. That’s how Philip created a compliant user manual with help from the User Manuals Template and the other available tools that I provided.

The best part of all this is that you can get the same results as Philip did by following this step-by-step process on how to create a user manual.

If you found this case study inspiring, I’d really appreciate if you would share Philip’s story on
Facebook or Twitter, or leave a comment below.

Tips and Techniques delivered to your inbox? 

Leave your email address and stay up-to-date with my tips and techniques and improve the quality of your content. 

SIGN ME UP!