The first thing when you start working on your training manual is knowing for whom you are writing. To do this, develop a picture of when, where, and how people will access your training content. Answering these questions helps you to right-size your content. With an understanding of things like audience skill level, their context, and their content preferences, you can build your content to fit their expectations and needs.
And, while you probably do, spending some time to flesh it out and bring the picture into clear focus will help you craft training content that truly solves your audiences problems.
A great training manual is easy to navigate. Someone encountering it for the first time feels comfortable discovering the information they need and a returning user is able to quickly find specific content and topics.
You can make sure this is the case for your training manual by strategically planning your content. Simply put, this means laying out all of your training material and organizing it in a logical fashion.
There are different themes you might use to organize and categorize the topics in your training manual. You could organize them by:. If you do have a lot of topics, consider placing them in groups and using headings and sub-sections to create a logical flow and organization within your manual. Use this structure to create a table of contents in the final manual. In many cases, there will be ideal ways to deliver your content.
Figuring out which it is requires thinking about both your audience and your content. You have a number of options for delivery. Common delivery mediums for training manuals include:. Questions like these will tell you if things like video, interactivity, and particular assessment strategies are viable techniques to include in your training material.
At the same time, some topics are more suitable to video, while others are better for text and imagery. You can combine different formats in one and provide rich, media supported content. TechSmith Camtasia is a great tool used by professional video creators, but is easy for beginners to get started with. There are also tons of great tutorials that will get you creating in no time. Additionally, we offer TechSmith Academy , a free resource where everyone from aspiring to advance creators can find all the resources they need to get started and level-up their skills.
Find content on tons of topics around training, video creation, and more. In many cases, this will fit your audience and your content best. In a few emails, I told him exactly what to do and how to use the relevant user manual template for his product type, step-by-step. The results are as follows:. This article describes exactly the steps we followed. Although Philip used one of our paid templates, I have made a free template that you can use to achieve exactly the same results.
There is only one difference. The paid templates already contain the mandatory legal parts for machinery , toys, electrical equipment or medical devices , which means that you can skip step 6. The free template is a more generic one.
When you choose to use the free one, make sure to follow the instructions from step 6. You can download the free template here:. Take the shortest way to a compliant manual. We have developed user manual templates for machinery, toys, medical devices and electronics that contain all legal content.
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 manuals. A user manual is a technical communication document intended to give assistance to people on how to use a product.
A good user manual assists users on how to use a product safely, healthily and effectively. 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. A user manual consists of textual visual information illustrations, screenshots, tables etc.
The user plays the central role when drawing up a user manual. A well-drafted user manual 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. 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. Different kind of products need a user manual.
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 manual might include things as:. The main tool that I developed in order to help Philip draw up his user manual is a User Manual Template. The template contains all the information and more from the list above.
It complies with the requirements for his product. 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. Based on the first template for Philip, we have developed templates for the following product groups:. The user manual template is an MS Word document that can be printed or placed online. 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:. 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:.
Ok, so now Philip has some basic knowledge about user manuals. 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. 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 is also called the intended use of a product, machine or device. A clear description of the intended use forms the heart of a user guide and determines with other limitations of use, such as technical or environmental limitations the safe envelope of using your product: it is the basis of ensuring safe, efficient and effective use of the product.
The description of the intended use frames your liability and is the starting point for the further contents of your user guide. Once you have determined the intended use, you can focus on providing the safety and user information for using the product for its intended purpose ONLY. Product safety laws, such as directives and standards, require most products to include a description of the intended use. An exhaustive range of functions or foreseen applications defined and designed by the supplier of the product.
Besides the intended use , you might want to add a description of reasonably foreseeable misuse as well. The use of a product or system in a way not intended by the supplier, but which can result from readily predictable human behaviour.
When you pay no or too little attention to the description of the reasonably foreseeable misuse, it may affect your liability as well. For example, when it can be reasonably foreseen that a certain cooling system used in hospitals, may be used as a system to cool organs, this should be described in the instructions.
Unforeseeable misuse should not be included in the instructions as this generally speaking does not affect your liability. As discussed previously, an instruction manual consists of various kinds of information that serve a specific purpose, called information types.
When you format information types consistently, your reader will consciously or subconsciously recognise them and link it to the function of the information type. The layout of the information type makes it easy to distinguish the various elements of information. A different layout will facilitate differentiation between various information types.
See this example where the heading, instruction title, instructions, product elements and illustrations are all information types that have been formatted consistently throughout the user manual. Using a style guide helps you to write and format documentation in a clearer way, and to keep a consistent tone of voice and style.
Another thing to be aware of when creating clear instruction manuals, is to avoid vague words. Examples of such words are thing, part and stuff. Using these words will make your user manual ambiguous. If you tend to use these words, you most likely still lack information. So ask someone or find unambiguous alternatives. Clear and to-the-point use of words will help the user to complete an action as safely and quickly and as well as possible. An action-oriented approach should have priority in general.
Your user should be provided with an immediate opportunity to act. Using Simplified Technical English can help you to write unambiguously. You can provoke action by giving less conceptual information and focus on giving procedures: users want to get stuff done and not read about it. The best way to learn is to act. 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.
When done correctly according to minimalism principles , video and interactive animation often is more effective than any other form of instructions. According to research, viewers remember information for a longer period making it more effective and viewers learn quicker making it more efficient.
Keep in mind that, as video might require a stable internet connection, it is less suitable in areas with bad reception.
Have a look at this incredibly funny video of Virgin America in which they present their safety instructions. You can use infographics, graphics, charts and diagrams to show patterns, organise and visually present data, show relationships, create overviews etc.
Symbols, icons and safety signs are often used in instruction manuals. They are characterised by having a predefined and clearly identifiable meaning and are used to transmit information. If a graphical concept is represented by a graphical symbol registered in a standard, it is highly recommended to use this symbol.
Examples of clear icons according to ISO Icons can be used to represent objects or functions. Make sure you use them uniquely and consistently for just one purpose. Never use different icons for the same object or function. For more directions on when to use text or visuals, see this post.
Luckily, more and more companies see the importance of both an attractive design and the use of several media to bring the information to the reader. There are many ways to communicate the use of a product with its user.
You can determine the media of the information based on the needs of the target audiences. Make sure that the media provide easy access to the information throughout the intended lifetime of the product. Therefore, always keep in mind the lifetime of the product and even consider mentioning it in the instruction manual. Some examples of possible media for user instructions are text, visuals photographs, safety signs, graphical symbols and illustrations , video including auxiliary means such as audio and subtitles , animations, speech, braille, augmented reality, virtual reality, leaflets or stapled booklets with text, illustrations and printed information on the packaging or on the product itself.
Although regulations slowly become less strict, always inform yourself about any legal requirements on the publication form in the country where you are selling your product.
See this article about online publication as well. Available technical authoring tools can help you to create both online and print user instructions, using the same single sourced content.
Single sourcing with MadCap Flare. Regardless of the chosen medium, it is also important to format the information for both the media and the target audience.
0コメント