Below are some guidelines to help you write clear and concise instructions. When creating documentation, there will be areas where there may be more than one way to spell a word, refer to an object, caption graphics, punctuate sentences, lay out a page, and organize information.
These are just a few of the decisions that writers must make when they create documents. If you use an established style guide, you may still need to establish some specific guidelines for your writing project. As you encounter any issues with styles, you can create your own additional style rules that address the specific needs of your project. If you would like to become a technical writer, you may want to consider registering for our Professional Technical Writing Course. It is an online course where you will learn how to write and revise instructions, technical reports, and software manuals key technical writing documents.
Use active voice Active voice emphasizes the user and is easier to read and understand. Compare the two sentences below. Focus on the reader User manuals should always focus on the reader. Speaking directly to the reader will: Reinforce the message that the information is intended for the reader Pull readers into the document and make it relevant to them Help to avoid passive voice by focusing on the reader Compare the two sentences below. Write clear instructions The primary objective of user manuals is to help users complete tasks.
Use numbered lists for instructions unless the instruction includes a single step. Use parallel construction for each step.
When you start each step with an imperative word, you are providing the user with clear cues on the required action for each step. Avoid using a system response as a step. You can incorporate system responses when necessary in the step that initiated the system response or you can mention the system response at the beginning of the following step, e. 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. Use a clean, readable sans-serif font. Ensure that the font size fits the needs of the audience. Avoid using multiple font styles. Use bold, italic or courier typeface for terminology, reference information or input.
Information that is printed onto. When information is only given on the packaging or in materials accompanying the product, make sure it is in a durable form. It should survive frequent use during the lifetime of the product and in an environment where the product is intended to be used. Part of how you present your user guides has to do with the language. It is generally agreed, and in most cases mandatory, to provide the instructions in the language of the country where the product is being sold.
For easy of distribution, these instructions are provided in 24 languages. I have now developed the content in chapter 2 texts and 3 visuals and the form in chapter 4, so it is time to finalise the user guide. The first thing you want to do is to proofread your instruction manual. Proofreading is the process of examining your written user instructions for errors. It can be difficult to proofread your own work and see the errors you made. If you're reading through your own work, your mind will read it like how it should have been written.
Once the proofreading has been done, you have a good starting point for the translations. Also, it is generally agreed that an English instruction manual is the best starting point for translations. Secondly, as English is the most spoken second language in the world, translating from English into another language is cheaper. It is easier to find someone to translate from English into Dutch, than from Dutch into English.
When finding someone to translate your instruction manual, try to look for a translator with similar translation experience. This might be a translator who is experienced in translating technical content, translating similar products, or in translating user guides.
When translating into multiple languages, working with a translation agency might save you lots of time, as they can take over the often complex project management. You might consider asking the translator or agency about their quality procedures and who is going to revise the text after translation. According to the standard, translators should have basic competencies as stated in proficiency level 1, should be as fluent in the original language as in the target language, should be native speakers in the target language and should be familiar with the type of product and any product-specific terminology.
As you know who your audience is and how your product works, you can increase the quality of your translations by providing the translator or agency a glossary or a list with the terminology that you want to use. The tool that you use to create your final instruction manual largely determines how the output, DTP and translation process is organised.
These tools have reuse of content as a starting point. By clearly separating content from form, the output process is automated, whereas with InDesign you will need several DTP hours. Also, most CMS or CCMS tools intended for technical authoring, allow you to create both online and print output using the same content.
Once you have finished and published your instructions, or maybe one step earlier, a usability test helps you to check if your users understand what you have assumed and written. Make sure to use naive and actual users that represent your audience and do not use designers or product experts. Watch the participants of the user research closely when they are using the user manual to get something done.
Examine where they zip through it. Note where they get confused, completely lost or fail when performing a task. You can also record and analyse the research. Listen closely to what the users have to say and use all this information to then adjust your instruction manual accordingly. To create a great first impression, you might have decided to make purposeful and effective use of colour or contrast.
Colour-coding also helps to aid navigation,. When using colour or contrast, make sure you consider the needs of disabled users, such as users with low vision or who are colour-blind. Test your use of colours during the usability research, to ensure they can be read by colour-blind users. Consider providing alternative instruction manuals in Braille, large print, audio etc.
Well, there is a lot to say about how to write a user manual. And I have only covered the most important topics! I hope that with this summary, I have given some useful input based on my ideas of writing good user guides.
By following the tips from this article and looking at the provided examples, I hope you have a better understanding of creating better information for use.
So, what's next? This case study including a free user manual template contains tons of additional information. If you find that this post is helpful to you, I would appreciate it if you could leave a comment below. Or how to write a user manual like this quick start guide for LIDL? Like this user manual for Gazelle? Like these user guides and online help? And finally, how to create an instruction manual , like this one: Then read on.
Watch this video to see if you can publish your user manual online. Serve information needs by gaining knowledge about your user The first thing you may want to do on your way to provide users with the right content is to get to know both the subject and user better. Ask yourself questions like: What describes the user? What is their age, gender etc.? What tasks do they need to perform? Why is the task being carried out? How frequently will it be carried out?
In what environment will the product be used? What language do they speak? Is the user under stress? What is their background? Is the product used professionally, commercially or privately? What technical experiences, qualifications, education, training, knowledge or skills do they have? Does the user have access to the internet?
Why is this important? To create a persona: Ask yourself the correct questions to identify and get to know the user. Find images online or in magazines that represent the user, their hobbies, the environment, their skills etc.
Use a photo editing tool or old-school scissors and paper to create a collage representing your user. Write an introduction in your user manual that describes the user. For example: These instructions are intended for the end-user of the [machinery name]. Persona of the user for the IsoVox recording studio Gaining knowledge about your users helps you to focus on what is important to them.
Have technical knowledge, but not too much This may seem like common sense, but knowledge really is the key to writing instructions that really help your users. So, technical people may not always be the right persons to engage customers.
Both too little and too much technical knowledge can have their disadvantages. Useful questions are: What is the intended use? What are the names of the most important parts?
How is the product delivered to the end-user? How do I transport and store the product? How do I use the product? How do I change the settings? How do I maintain the product? How do I repair the product? What are the possible errors and how do I solve them? How do I dismantle and dispose of the product? Are there any spare parts available? What are the technical specifications?
What risks do I encounter during the stages of the product life cycle? When studying existing material, you will most likely find similarities and differences. So what exactly is a subject-matter expert? Some tips when interviewing your SMEs: Make sure to do your homework well.
Problems are very specific, such as: How do I attach the feet to my microwave? How do I replace the mould of my machinery? What does the red flashing LED light mean? Am I allowed to clean the housing of my product with a detergent? So the main problem would be: How do I make the Roof Washer ready for use? How do you process and organise all this? A few methods and tools that can help you: Create the table of contents on the go; Use mind mapping ; Use information mapping techniques; Use old-school post-its.
Example of a mindmap All methods are based on the following principles: Break up all relevant information into small and manageable chunks; Each information chunk should be limited to a single topic; Label each information chunk in such a way that it identifies its contents, meaning that the description that you come up with should describe the content.
Organise and structure information, while making sure you are consistent in organising, formatting and sequencing information and be consistent in the use of terminology. Again, you are automatically further defining your topics here. User Manual A user manual or instruction manual is one type of information product. The user manual, installation manual and quick start guide of a product Topic User manuals are structured around topics.
Topics need to be grouped logically. Instructions If a topic is complex, it may contain several chunks, indicated as instructions in the above information type model. Steps A step is a detailed description within an instruction. Illustrations contribute to a better understanding of what needs to be done.
This is the magical number of objects an average human can hold in short-term memory Miller, If necessary, a step can be enhanced with embedded safety warnings, tips with a more detailed description on how to perform the step or error recognition in case a step is done wrongly. When I apply this model to the process of creating user instructions, it would look like the following: Organise your topics for the sake of easy navigation I would like to talk a bit more about the importance of your table of contents and thus the way you organise your topics in the instruction manual The table of contents ToC should be incredibly carefully crafted.
Why does the ToC play such an important role? Example of a default table of contents When I think all is completed, I add my product specific topics to the default ToC, organise them and finalise my table of contents.
Engage your audience by avoiding jargon in your instruction manual Instruction manuals written by technical people tend to contain huge amounts of jargon.
What is jargon? Help your user to find what they are looking for by meaningful headings A heading is a title at the head of a page or section of a book. This example shows a heading that clearly covers the content. Have a look at these examples: Notice that the phrasing of headings is consistent: The first-level heading covers what the entire chapter is all about. Although this is not the only right way to format them, I will give a style example here: Make first-levels all-caps; Make second-levels title-style caps: init-cap only the first word and any proper nouns and verbs; Make third-levels sentence-style caps: init-cap only the first word.
Using an automatic gateway to move persons children standing on it when it is opening or closing Example of the reasonably foreseeable misuse of a helicopter platform When you pay no or too little attention to the description of the reasonably foreseeable misuse, it may affect your liability as well.
Reasonably foreseeable misuse or unforeseeable misuse? Support clarity with clear understandable user manuals As discussed previously, an instruction manual consists of various kinds of information that serve a specific purpose, called information types. Which information types can YOU distinguish here? Writing instructions: Provide an immediate opportunity to act to get stuff done 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.
There is this interesting paradox: The best way to learn is to act. Look at this example based on the principles of minimalism , that contains this balance: Or this minimalist example 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.
Also, within one sentence, you should follow the right order. To select German as your default language, select Deutsch when clicking on Language in the File menu Select Deutsch. Pretty straight forward, right?
Use the active voice to write easier to understand steps Make sure that the information you give is as simple and as brief as possible. The subject and verb are always clear in sentences with an active voice. Or you can mention the response at the beginning of the following step.
The language window opens. In the language menu , select Deutsch. Click SAVE. Minimise cross-references to prevent confusion Every now and then you might want to add cross references to your instructions. Example of a cross reference to the entire section Safety Information In general, cross-references should be kept to a minimum.
Referring to a sequence of steps, like in the example below, is not recommended. Charge the battery. See 2.
How to Charge the Battery. Force to consider details by using a style guide 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.
A style guide enhances comprehensibility. Ensure safety by using words like must, shall, should and could correctly The correct use of words to indicate requirements and recommendations is standardised in the American ANSI Z Include error handling to save your user time, reduce frustration and anxiety No matter how well a product or piece of software has been designed, things undoubtedly go wrong when using it. You can use the template yourself to determine who your user is.
Action: Use the template to describe your user s. I am a HUGE fan of visualizing things. So if you want to take defining your user one step further, I would suggest you visualise your user in the form of a persona.
When creating a persona you are giving your user a name, age et cetera, so it becomes a real person that represents your user. Typical problems might include: installing the product, using the product, using the product safely, maintaining the product and disposing of the product.
I asked Philip to identify the problems and solutions that his user might encounter during the product lifecycle. In order to do so, I created another template for Philip.
Our user manual templates are compliant with this standard. Action: Use this template and the instructions on the first tab to identify the problems your user might have during the lifecycle of your product and present their solutions.
Philip has now identified the problems a user might have with his product during its lifecycle and he has now thought of the solution to solve the problem. In other words: Philip has defined the topics for his user manual. Each topic can only be about one specific subject, has an identifiable purpose, and must be able to stand alone.
A user wants to solve one problem at a time. A topic will become a section in the user manual. It can be a chapter or a sub- paragraph.
As soon as a user is looking for an answer to his problem, he will use the table of contents to find out how to navigate to that answer. I asked Philip to structure the topics and define their place in the user manual, by assigning a certain topic to a specific chapter or sub- paragraph.
You have now created the Table of Contents ToC. The ToC is the outline of your user manual. Each topic in the user manual gets its own heading. The headings are the sub- titles that precede the actual text. They appear in the ToC, so the user can navigate to the needed information. Because the ToC entries play such an important role in helping your user find their way, and to help them skip what is NOT important, they need a bit more attention.
Basically, you should try and work with three levels of headings: first-, second- and third-level headings. The first-level heading describes what the entire chapter or section is about e. A third-level heading uses noun-phrases e. Packaging contents and Tools to be used. Meaningful Headings tab. Dependent on the market where your product is placed in or put into service, and dependent on the product group your product belongs to, specific legislation applies to your product. These requirements also include requirements on the content of your user manual and safety instructions.
In order to sell your product in a specific market, you should make sure that your user manual complies with these requirements. These two articles below will tell you how you can find out exactly which legislation applies to your product for the European and U. Pro tip: when there is a Declaration of Conformity available already, you can find the applicable directives in there. Philip didn't need to conduct these steps, as the template he used already contained the legal content as required by the relevant directives.
For his product, it means that the following information is required for the user manual for his product:. This standard has been harmonised in the EU. Compliance with harmonised standards provides a presumption of conformity with the corresponding legislation! I have also created an IEC checklist that can be used to double check that your user manual complies with this standard. In order to create an internationally compliant user manual, you should always make sure your manual meets the EU, US and requirements.
I asked him to adjust the table of contents of the template according to his own table of contents. Without removing and mandatory elements of course Do you remember from step 4 that I asked to start the numbering of the sections with chapter 4?
Once you download the user manual template doc yourself, you will see that a few standard chapters have been added, as well as some appendices. The purpose of your product, or better: the intended use, is the heart of a user manual and forms the basis of ensuring the safe and healthy use of the product. The way the intended use is described also determines your liability and affects the further contents of the user manual. The most legislation requires you to include a description of the intended use in the user instructions.
The international standard for user instructions, the IEC , provides the following definition for the intended use:. An exhaustive range of functions or foreseen applications defined and designed by the supplier of the product. By describing the intended use you determine the safe envelope of the product. And once you have determined the intended use, you can focus on providing only those safety and user instructions for how to use the product within the given envelope. Additionally, to the intended use, many more standards, directives and regulations also require you to include a description of the reasonably foreseeable misuse.
For example, the reasonably foreseeable misuse of an aggressive detergent could be the use of it in a food processing environment. Paying too little attention to describing the reasonably foreseeable misuse will affect a company's liability. If the defectiveness of a product needs to be determined, all circumstances will be taken into account. That includes the reasonably foreseeable use of the product.
The description of the intended use determines which instructions are given in the rest of the manual. For example, if a cooling system is only used for cooling certain medications, then only these procedures need to be described. When it could reasonably be foreseen that the cooling system may be used as a system to cool organs, this should be described in the instructions. By doing so, you, as the manufacturer, will limit your liability and you can focus on only describing how to use the system to cool medicines.
Figure 1. Reasonably foreseeable misuse? Even though the intended use has now been clearly defined, this does not mean that using a product is completely without any risks.
To identify the hazards that come with the use of a product, you can conduct a risk analysis. A risk analysis can also be mandatory for certain product groups, such as low-voltage equipment, toys, machinery and equipment for use in explosive atmospheres. Standards, like the ISO , have been developed on how to conduct a risk analysis. According to this method, there is the following hierarchy of risk-reducing measures:.
This means that the user guide should warn of any residual risks related to the use of the product. This is done with safety warnings. A good safety warning describes the nature of a hazardous situation, the consequences of not avoiding a hazardous situation and the method s for avoiding it. Rotating parts. Risk of serious injuries. Keep hands clear. Then you want to warn the user where a hazardous situation might be encountered.
Do this. Do that. This is embedded safety messages. General text general text general text. In the EU, depending on the kind of product, it might be allowed to provide only the safety information in printed form and the rest of the information online.
Action: conduct a risk analysis and craft your safety messages using this template. Now I asked Philip to create all other content, such as the procedures, technical specs and legal information. Again, for most product groups there are paid templates available which might make the work easier. These templates contain all legal texts, mandatory disposal information, copyright statements and comply with the IEC standard on user instructions.
When using the template for crafting the safety messages, I asked Philip to indicate whether a safety message is a supplemental directive, or should be placed as a grouped, section or embedded safety message. A user manual should give assistance to people by providing information about how to use a product. The crafting of meaningful headings is one of the tools that aid users in finding information. Philip has now created the draft version of his user manual, using the user manual 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.
0コメント