Guidelines for creating a user manual

Video games come with manuals to tell you which buttons to push to shoot the bad guys. Software documentation shows you what your purchase can do and how to do it. Lawn mowers and snow blowers have product guides to show you how to start the engines and where to refill the fuel. Skip down to how to make user documentation. You know your product is great.

You want your customers to know it, too. User documentation helps ensure your customers or users actually learn how to get the most out of your product. User documentation is easy, right? I bet most of you have had similar experiences. A great user manual or product guide shows your customers that you care not just about whether they buy your product, but whether they have a truly great experience actually using it.

Customers who feel that you care about them beyond their wallet will keep coming back to you. If you want them to shout to the world about how much they love your products and services, providing awesome user documentation is an essential part of that post-purchase experience. Having great user documentation helps out your support team in two major ways. Your product support team can use documentation to help better support your customers when they ask for help.

When you include essential pieces, such as a table of contents or index, they can quickly find the information they need. Even though each product is unique and will require different elements to create truly great user docs, there are some end user documentation best practices to follow no matter what.

No one wants to feel dumb, and language that makes your customer feel that way is certainly no way to foster a great experience. Use simple, plain language whenever possible to help your customers understand even the most complex concepts.

It sounds like a no-brainer, but writing in plain language about a product or service you know front-to-back is more difficult than you might think. Write the documentation in an easy-to-read way. Keep documentation as simple as possible to achieve its goal.

Long blocks of text and pages tightly packed with written and graphic content can make user guides or manuals feel intimidating and unfriendly. Customers who are intimidated by your user materials are far more likely to call your support team for help than they are to try to solve their questions on their own.

Visual content, including images, annotated screenshots, graphics, and videos, quickly shows someone how your product works. Recent research from TechSmith shows that people actually absorb visual information faster and perform tasks better when instructions are provided with visual or video content.

Visual content also helps break up long blocks of text and can help eliminate a lot of the text that makes many user guides or manuals feel intimidating and unpleasant. Popular ways of including visual content in user documentation include screenshots , screen recordings , tutorial videos , and more. Have you heard of simplified graphics?

Action: Adjust the User Manual Template to fit your brand identity, or download the InDesign user manual template and adjust it. Philip now has both the content of his user manual Word file and the user manual 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.

Depending on the market in which you are going to sell your product, you might need to translate the user manual. In general, a user manual should be available in a format that is easily accessible to the user.

That can be printed, or used online or on-device. In the European Union, for some product groups, it is still restricted to provide the user manual printed with the product. However, as of April , 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.

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. And he did this without any knowledge of technical writing. 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. I have listed this information below. What is the definition of a user manual?

Other names, or other forms of a user manual, might be: User guide 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 to assist a user , secondary goals could be creating a better user experience and meeting legal requirements.

What information should be in a user manual? Based on the first template for Philip, we have developed templates for the following product groups: Medical Devices Toys Machinery Electronics What formats does a user manual have?

Through the following links you can download a user manual sample for documentation: IKEA installation instructions Jura user manual Step 2 Identify the User s of Your User Manual Template Ok, so now Philip has some basic knowledge about user manuals.

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. I did this for Philip. If the problem is too complex, you could break it down into chunks. Action: To define the structure of your user manual: Copy the content from the Lifecycle [product name] tab to the ToC [product name] tab.

On the ToC [product name] tab , replace product name with your own product name. Add a column to the left.

If applicable, organize your sections logically. Determine what topics will become chapters by adding chapter numbers.

We will add some more chapters in the next step. Determine what topics will become paragraphs by adding the section numbers. Determine what topics will become sub-paragraphs by adding the subsection numbers. Step 5 Create Meaningful Headings Each topic in the user manual gets its own heading. So, Philip has just created the sub- titles for his topics. 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. 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. 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.

How to Create Compliant Manuals for the EU How to Create Compliant Manuals for the US Philip didn't need to conduct these steps, as the template he used already contained the legal content as required by the relevant directives.

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. 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. 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.

The user manual template complies with this standard. Study the IEC checklist to ensure your manual complies with the standard. Action: To adjust the user manual template: If you want to work with the free template: Download the free user manual template Word or Change the section headings according to your own ToC.

Do not adjust the Table of Contents. The table of contents can be updated automatically once you have adjusted the section headings. Add the mandatory content as determined in step 6 of your manual. If applicable, modify sections and the appendices according to your own needs. 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.

Action: write the intended use and the reasonably foreseeable misuse of your product. 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.

According to this method, there is the following hierarchy of risk-reducing measures: Inherently safe design measures Safeguarding and complementary protective measures Information for use This means that the user guide should warn of any residual risks related to the use of the product. BUY NOW 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. Then, include setup instructions, explain basic operations, and create a product summary to go at the end of the manual.

You can also include a section on product care to go over cleaning, basic maintenance, storage, and troubleshooting information. To learn more about the ideal writing style for user manuals, read on! Did this summary help you? Yes No. Log in Social login does not work in incognito and private browsers. Please log in with your username or email to continue. No account yet? Create an account. Edit this Article. We use cookies to make wikiHow great.

By using our site, you agree to our cookie policy. Cookie Settings. Learn why people trust wikiHow. Download Article Explore this Article parts. Tips and Warnings.

Related Articles. Article Summary. Part 1. 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.

You can never please your entire audience; write the manual to suit the target or largest audience. 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.

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.

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. 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. Part 2. Organize the manual logically. The user manual should proceed in a way that the user will find most beneficial. At the same time, often users need to learn first in order to act. Look at this example based on the principles of minimalism , that contains this balance:. In much conventional user documentation, not much priority is given to supporting actions a user needs to perform at the beginning of the instruction manual.

Many user manuals start with explanations, technical data, safety instructions, process descriptions etc. This, for sure, can be valuable information at some point, but mostly distracts the users from getting to their goal. Try to include only the absolute minimum of must know information in your user manual and consider all the nice to know information as obsolete.

The user guide stimulates a user to activate relevant prior knowledge and to depend more on their own thinking when you do not explain everything. When you master the skill of minimising background information and provide just enough information so that the user can complete a task or understand a concept, your instructions will become much clearer.

Many user guides contain instructions that are incomplete or incorrect. When writing, it might help you to perform all of the steps yourself as you write. This ensures that what you write is the right way to do things and it helps to focus on the must know information.

It will also increase the chance that nothing is forgotten and the overall quality is improved. In those cases, discuss all steps with an SME, think them through thoroughly and have everything written checked.

Make sure to provide step-by-step sequences that are placed in the correct order and follow the timing and sequencing of the actual operations. To select German as your default language, select Deutsch when clicking on Language in the File menu.

This example shows visual stepping stones: steps are numbered with 1, 2 etc. Adding these makes it clear to the users that there is a need to follow the steps one by one. Short, simple sentences with just one instruction, or at most a small number of closely related commands, per sentence work best. Write the steps to task completion, meaning that you tell the user exactly what to do in order to complete a single task.

Avoid creating dead-ends and make sure that after going through the sequence of steps in a certain topic, the user has solved the problem: each topic has a clear beginning and ending, this is in contrast to a book that you read entirely from beginning to end.

Make sure that the information you give is as simple and as brief as possible. Instructions should be written in the present tense and active voice, using strong verbs. The active voice emphasises the user and it is easier to read and understand instructions that are written using the active voice. In this sentence, connect is the active verb and keyboard , USB port and remote unit are all subjects. It is much clearer that the reader is the person who will complete the action in the sentence written in active voice.

By using the active voice , your instructions will be clearer, more concise, and direct. It is ok to incorporate product or system responses when necessary in the step that initiated the response. Every now and then you might want to add cross references to your instructions. For example, you might want to refer to a sequence of steps that have been given somewhere else in the instruction manual. Or you simply want to refer to an entire section. Example of a cross reference to the entire section Safety Information.

In general, cross-references should be kept to a minimum. Letting your users go back and forth through the user manual is not user-friendly and confuses them. Referring to a complete section like in the example above , which is an addition to a certain topic but a topic on its own, generally is ok to do.

I have emphasised the importance of consistency several times already, but I will mention it again here: it is crucial to express terms, product elements and units in a consistent manner. Use consistent terminology in the instruction manual themselves, on the packaging, in other collateral materials and on the product itself marking and labelling.

Of course, sentences should be grammatically correct, written for the target audience, and jargon should be minimised. Avoid abbreviations and acronyms, unless it can be assumed that they are familiar to the audience you write for. Your user already bought the product. All of the above guidelines can be put in a style guide. A style guide provides consistency and stimulates to carefully consider all details: the presence of a style guide will force you to look closely at each single sentence.

Once you have established your own style guide that covers for example your writing style, wording, consistent use of terms, ways to address the readers and design of text and page layout we will discuss this later , you will need to apply it to the entire instructions for use. Regardless this is a U. S standard, I also like to apply it to the instruction manuals we write for other markets.

The ANSI standard states that the correct verb form for indicating a requirement is shall. The word shall is understood to be mandatory. The universally accepted use of must instead of shall is not recognised by the standard. For example: The product shall only be used by persons who have fully read and understood the contents of the User Manual. The correct verb form for indicating a recommendation, as defined by the ANSI, is should. Or to speak in ANSI terminology: should is understood to be advisory.

For example: After each use, the device should be disconnected from the mains. When there is excessive freedom of behaviour, or no guarantee that something will happen, you can use the word may. This word is understood to be permissive. Using might instead is not allowed. For example: Some individuals may experience a mild tingling sensation when first using the device.

I have experienced a situation where U. No matter how well a product or piece of software has been designed, things undoubtedly go wrong when using it. As a technical writer you should pay attention to this. Users of products make many simple mistakes. Correcting these mistakes can be time consuming. So it is therefore important to add error information to instructions that users might misunderstand. Providing error information AND providing it there where it is needed, is one of the most underestimated aspects of user documentation.

There are several ways how well-designed instruction manuals can prevent users from making mistakes. For example by providing a safe sequence of steps, using short and simple sentences, minimising jargon, using active verbs etc.

Research [1] has shown that even experienced technical writers generally do not predict really well what problems arise when their documentation is used. The best way to find out what errors users will face is by usability testing. See Conduct user research to check what you have written. When you have found the most common errors that occur, a model for adding problem-solving information to your user manual suggests the following stages:. In other words: when designing error-information, make sure you support the user in detecting, diagnosing and correcting mistakes.

Error information is most effective when it is given as near as possible to the source where and when the error occurs. This is often directly after a certain instruction. When providing error information on the spot, the mistake will be detected and hopefully solved, before they can lead to other mistakes. When you provide the error information on the spot, it will save your user time, reduce frustration AND the anxiety of learning about using the product.

I discuss this in more detail in this podcast :. First of all, because it has to do with compliance, which is a largely overlooked topic by most tech writers. Information on compliance, product safety and what exactly to include in your user manual is hard to find. The websites of our legislators can be quite overwhelming. Secondly, I like the contradiction between creating a compliant and user-friendly instruction manual at the same time. Some technical writers like to over-warn.

I have seen user guides with nothing but warnings and really not a single instruction. Over-warning is at odds with an action-oriented approach. What would your user experience be when a 40 page instruction manual has its first actual instruction on page 32, after more than 30 pages of warnings and process descriptions?

No matter how well and safely designed a product is, using a product often comes with certain risks. Risks can be identified by conducting a risk analysis. It is generally agreed in international standards that there are three ways to reduce those risks:. You can adjust the design of your product, equip the product or user with safety measures such as safeguards, personal protective equipment or provide safety instructions.

These three risk reducing measures should be considered in this specific order. So a user guide should never be used to warn for risks when the design can still be improved. For the user manual this means that there can be distinguished four types of safety instructions: supplemental directives, grouped safety messages, section safety messages and embedded safety messages see this post for more information about these.

Considering the number of warnings, the use of this electric toothbrush seems just as dangerous as working on a nuclear power plant. I am not saying not to use any warnings at all, but it definitely is possible to reduce the number of warnings drastically in many cases.

When you do decide to provide a warning instead of an instruction, make sure to structure the warning well. Nowadays, the meanings of signal words are similar in several available standards describing risk levels. Signal word used to indicate an imminently hazardous situation which, if not avoided, will result in. Indicates a hazardous situation that, if not avoided, will result in death or serious injury. Signal word used to indicate a potentially hazardous situation which, if not avoided, could result in.

Indicates a hazardous situation that, if not avoided, could result in minor or moderate injury. Depending on the product you are writing for, chances are there are legal requirements on the content, presentation and format of your user guides. These can come from federal laws in the US, directives or regulations in the EU or similar legislation in other countries or states.

Standards can be used, if not made mandatory, in order to comply with the CE requirements. For example, medical devices are the most heavily regulated products. By complying with the legal requirements and applying standards, you create a user guide that is legally compliant.

This will help you to avoid any legal pitfalls, will let your product pass tests and customs, decrease your liability, provide competitive advantage and make sure your users can use the product more safely. Generally speaking, the following process should be followed to create compliant user manuals:. I have written about this process in more detail for both the American market and the European market. Also, these templates might help you create CE-compliant user manual template for machinery , user manuals for electronic devices and toys, or the instructions for use for medical devices.

Also for the US, we offer templates for machinery and medical devices. How to use the Operator Manual Template for to create a machinery manual:. An essential part of a clear user manual is the way your user can navigate to the information they are looking for. Much of this has been discussed already in the previous chapter.

But there is more than adding a table of contents, page numbering, clear headings and a logical structure. Instead of ordering your topics according to the life cycle of a product from unpacking to disposal , you might want to divide your section ordered by chronology of use, expertise level beginner or expert , functional category or frequency of use. You can code your hierarchy with tabs or colours or emphasise the importance of certain information types with contrast, colour, shading and embolding, which is actually part of how you present your instruction manual see Chapter 4.

Another way of guiding your user to the right information is by including an index or glossary. An index is an alphabetical list of names, key words, product elements, life cycle stages etc.

A glossary is an alphabetical list of words relating to the specific subject you are writing about, with explanations. So it is actually a brief dictionary. Example of a glossary. Once you have used all these tips and examples to write the content of your manual, it is time for reviewing your work. You have now created the draft version of your instruction manual.

Internally, we name this version the textual content design we could put this one in the glossary, lol. Ask all persons with in-depth technical product knowledge that contributed to delivering information, to review the work so far.

I prefer to work with a technical authoring tool for the review process or simply via Google Doc. Visuals include all kinds of graphical representations, such as line drawings, photos, screenshots, video, symbols, tables, charts, graphics and infographics.

You can use line illustrations to support, replace or augment text and to present a chronological sequence of a process or steps to be followed. Make sure that the sequence of illustrations that you place in your user guide is logical and comprehensible.

When you place illustrations as close as possible to the text to which they relate, it is clear to which textual instruction they belong. Ensure that related text and illustrations are viewable at the same time and that they support each other in order to enhance comprehensibility. Compared to photos, you have much more freedom with illustrations to focus on important details. You can easily leave out less relevant information or enlarge certain parts.

Keep in mind that creating comprehensible illustrations requires skills. Although there are many tools available that can support you, having them created by a competent graphic artist or technical illustrator might be a wise decision. When creating illustrations, keep printing quality or screen resolution in mind. Illustrations used on screens require a resolution of 72 dpi and, for print, resolutions of minimum dpi are preferable.

Add numbered captions to your illustrations so it is clear to the user what the illustration is about and so the illustration is easy to identify when referred to in the text.

Illustrations can also be used to identify product parts and main functions, represent a schematic version of your product or for example the electric scheme. Sometimes photos are used instead of illustrations. However, I really prefer the use of line illustrations as these are often much clearer. When creating illustrations, you can leave out irrelevant information or easily emphasise important information. With photos this will be more complicated. Screenshots can be used to visually represent the user interface of a control panel, software on a desktop computer or an app.

Screenshots can give an overview of functionalities or be used to show what needs to be done or to present the result of a certain action. You can use tables to organise numeric or verbal data.

For example, technical data are more legible when presented in a table. In many cases, a table can fully replace text. Make sure to set out tables clearly, informatively, and in a consistent design.

Position tables next to the relevant text. As an exception, reference tables such as a spare part list can be placed in annexes. The use of video could be your choice when you clearly want to demonstrate something, show movement, a state or force.

Also, as video is increasingly popular, you might want to use it when reaching as many people as possible is your goal. Video can be realistic filmed with a camera , a 3D animation or an illustrated animation, as long as you keep in mind that videos should be short and relevant. When using video, synchronised spoken or written text, or both, can be used to accompany the sequences. Another increasingly important form of animation, is interactive animation.

Interactive animation can be best described as a sequence of visual and auditory elements. It can best be used to explain complex processes, such as a sequence of installation instructions.