You might organize this section as a list of common problems and their solutions. Group similar problems together under a logical heading. This way, users can find specific problems quickly. Part 4. Read other user manuals. Before writing a manual for your own product, look at other effective user manuals. Pay attention to the structure, word choice, and sentence style. Major brands like Apple, Google, and Microsoft produce strong, effective user manuals that can help you produce a more thoughtfully written user manual.
Read the manuals for similar products that you are selling. For example, if you're selling baby products, read baby manuals, not tech. Select your standards. Standardizing spelling, word choice, and phrasing will make the user manual more user-friendly. The Chicago Manual of Style and the Microsoft Manual of Style might also be useful style guides when writing your user manual; consult both to see if one will work for your manual.
Use active voice. It is easier to understand than its alternative, passive voice, in which the subject is undefined. Examine these two sentences, the first active and the other passive, for examples of each: You should open the package slowly and carefully. The package should be opened slowly and carefully. Write numbered instructions.
Numerically ordered instructions will help the reader stay more focused on the process of using, connecting, or building the product in question. Instead of writing a long, rambling paragraph, or a series of un-numbered paragraphs, write your user manual with simple, explicit steps, each numbered clearly. Start each step with an imperative. An imperative is an action-oriented verb. By starting each step with a verb, you will clue the reader in to the action required to complete the step.
The screen will blink and turn blue. Use simple words and vocabulary in order to explain how the yo-yo works. In general, try to avoid jargon and technical language. To be effective to the broadest array of users, try to write at a sixth to seventh grade reading level. Ensure your translations are accurate if you are shipping a product overseas.
Hire a translator to translate your user manual into the native language of the country that you are shipping your product to. Alternatively, use an online translating app, but ask a native speaker read over and edit the translation for errors. If there are multiple language groups represented in your audience, include translations of the user manual in each relevant language. The translator should be familiar with the product, as there may be different words for specific terms in the target language that not are word-for-word translations.
Keep your writing brief. Instead of a few long paragraphs, use many short paragraphs. Look for logical breaks in each section and put useful information into one or two-sentence chunks. The same applies at the sentence level.
Keep your sentences short and simple, rather than long and rambling. This won't cause the word-count to go down, but the line breaks will make it easier to read. Proofread the manual.
A manual can lose credibility due to grammar and spelling mistakes. Have a coworker or technical writer edit and proofread the manual as well. In addition to spelling and grammar, a proofreader should look for: [11] X Research source Passive voice Ambiguous or confusing language Complicated sentence structure Overly long paragraphs.
Joe Simmons Corporate Trainer. Joe Simmons. Keep your instructions as focused, simple, and digestible as you can. Also, try to tailor the manual to day-to-day activities, which helps boost your employees' courage, competence, performance, and productivity. Not Helpful 0 Helpful 0. Include your email address to get a message when this question is answered. People learn in different ways; if possible and appropriate include visual aides or links to online videos in the manual to assist visual learners.
Helpful 0 Not Helpful 0. You Might Also Like How to. How to. Corporate Trainer. Expert Interview. More References 2. About This Article. Co-authored by:. Co-authors: Updated: July 9, Categories: Technical Writing. Article Summary X To write user manuals, start by breaking up the bulk of the content into chapters or sections that make sense for the product's use, then kick off the manual with a table of contents and glossary.
Deutsch: Eine Gebrauchsanweisung erstellen. Nederlands: Een gebruikershandleiding schrijven. Thanks to all authors for creating a page that has been read , times. I like the concept. More reader stories Hide reader stories.
The writer of a user guide often does not realise that the reader does not have the same background or knowledge about a product. Remember that you are writing to communicate the use of a technical product, not to impress.
If you realise that, you will automatically use less jargon. The description of your topic is a heading and will get an entry in the table of contents ToC. The ToC is consulted by the readers, to get as quickly as possible to the topic that contains the information they are looking for.
A heading marks off the boundaries between topics and subtopics of an instruction manual. A good heading covers the full content of the topic it belongs to. Try to work with a maximum of three levels of headings: first-, second- and third-level headings.
Don't overdo the levels of headings. Notice that the phrasing of headings is consistent: The first-level heading covers what the entire chapter is all about. The second-level headings use the how style of phrasing. The third-levels use noun phrases. Make sure to craft the phrasing of headings so they are self-explanatory.
Clear styling of your headings helps your reader to identify the level of a topic. Although this is not the only right way to format them, I will give a style example here:. Also note that this style can not be used in all languages.
In German for example, nouns should always be capitalised. A clear user manual should describe how a product shall be used according to its function and within the expected product life span. 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.
The two biggest types of products here are physical and digital. This difference between these two affects how you go about making your user manual. Do you need to take your own pictures using a camera and import them onto your computer, or do you need to take screenshots of your screen to show a digital process?
For this post, we will focus on the latter, and use Snagit to capture our screenshots. Now, this is the long bit — the process of taking screenshot after screenshot to make sure you can thoroughly explain your product.
The ability to edit your screenshots to show specific details is important to you and the viewer. So, open Snagit, and get to it! With Snagit, there is a built-in editor for everything you need when making a user manual. You can add arrows, boxes, text, and more. One feature that I want to focus on is the simplify tool. Simplified User Interfaces SUI are great to ignore all the unnecessary information, future-proof your content, and make your visuals appeal to all, no matter the language.
As you can see from the image on the right, your eyes immediately go to what is being showcased.
0コメント