Preparing a user manual

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. After it has been simplified, the screenshot is much easier to understand and follow.

While screenshots are helpful by themselves, combining them with copy can provide a more detailed explanation than pictures alone. I prefer to organise topics in the ToC based on my audience's needs and the purpose of the information, following the life cycle of the product.

Mostly I start with a default table of contents. When gathering information, as described in the previous sections, I write down the names of my topics on post-its, label them and put them on my wall or I create a mind map online. 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.

Mostly, we discuss the ToC with the company that hired us. Another important thing to take care of and which is essential to help your users finding solutions through the ToC, is to craft the name of your headings really well. We will discuss that later in more detail. As some last notes, I want to mention that the sections about mapping, organising and structuring information are quite theoretical, but being skilled in this is one of the most essential skills of a good technical writer.

The only way to check if you have done it right, is by checking if your users can quickly find the information they are looking for. Once we have determined our topics and structured them to form the table of contents or menu structure for online help , we can start with the actual writing of the content. The main goal should always be to write a user manual to make safe, efficient and effective use of a product possible.

Jargon is unnecessarily complicated language that is mostly used to impress instead of inform your audience. I am not saying that you should not use any technical terms. Often you need them to explain a product well. The starting point should be to create instructions that are as clear as possible. Using terminology that is not part of the usual vocabulary of your reader does not contribute to that. Often, specific terms are useful and may even be the only known terminology within a particular audience.

In those cases, using them is the clearest way to communicate with your target group. However, if your readers are specialists, going beyond the use of the necessary technical terms may cause misunderstanding and will alienate your reader.

One of the most heard about complaints about user instructions is when there is too much use of jargon. 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. The introduction of a user manual usually begins with a message of appreciation to users for selecting the product and a general product overview.

The conclusion usually ends with details on how to contact the company, as well as information about the warranty and any disclaimers that might be needed. Step: 7 Be Brief and Detailed User manuals need to be brief and detailed. Step: 8 Verify Accuracy Make sure that all of the information in the user manual is accurate. Step 9: Proofread Carefully Proofread carefully to make sure your document is free of all kinds of errors, including spelling, punctuation and grammar.

Step Format for Readability Covering all the key information readers need is critical for a user manual, but the document also has to be user-friendly and easy to follow. Choose an appropriate font. It is generally best to opt for a sans serif font such as Arial or Calibri. Depending on your audience, you may need to use a larger font. Use headings to highlight transitions from one section to another.

Include subheadings within heading sections as needed. Present steps that must be followed in order in a numbered list format. Step Include a Table of Contents A table of contents is key when establishing what tips on writing user manuals you should take into consideration.

Step Consider Adding an Index If the user manual is fairly long and detailed, consider adding an index at the end of the document in addition to including a table of contents at the beginning. Step Get the Document Reviewed Once you think the document is ready, get someone else to review and edit the document.

Key Business Writing Skill Writing instructional manuals is one of many types of business writing. Related Articles. Advertisements must demonstrate clearly what the purpose and basic operational guidelines of a product are, and you should use these sources when writing your user manual. For the user manual of a product to be effective, it needs to be written in concert with labels affixed directly to the product.

Ensure your device is legally licensed for sale before writing instruction manual. There are several important ways you can streamline your manual. You should place a bold heading at the start of each section with each word capitalized.

Another way to streamline your manual is to use two columns, one on the right with text and the other just to the left of the text with bullet points, numbers, or small icons like warning signs or red exclamation marks. You could also use a flow chart to provide the user with directions. Think about your product and how each method might be of use when writing your user manual.

However, avoid mixing different layouts within a manual. Choose one and stick with it. Part 2. Organize the manual logically.

The user manual should proceed in a way that the user will find most beneficial. Split the manual into chapters or sections that make sense for the product's use, and include a table of contents toward the front of the manual so each section can be found quickly.

A table of contents is especially necessary for longer manuals. A glossary or index is needed when there are many terms to explain that your audience may not be familiar with. However, glossaries are not recommended; the best choice is to explain confusing terms in the text of the manual itself.

If you choose to include a glossary, place it in front of the manual, just after the table of contents. A list of tables or figures is only necessary if there are more than a few tables or figures in the manual. An appendix is needed for things that should be explained but cannot be explained at another point in the manual because it would disturb the flow and focus. Include necessary warnings. The general warnings or cautionary information should provide information about potential threats improper use of the product could incur, including death or serious injury.

These warnings should be placed in the very front of the manual after the cover page so that the user sees them first. Specific warnings should also be included in the text of the user manual just after or just before a potentially hazardous step is suggested.

For instance, a general warning for an electric device might be to avoid using it during rain. A specific direction might be to ensure that your hands and the device are both dry before plugging the device in. You could explain the benefits of following the manual instead of working independently. Describe the device. The graphic should properly label and name all the switches, knobs, and attachable parts that the device includes.

Include setup instructions. The setup section should include basic information about how to prepare to use the product or device. If the device cannot be constructed or set up by a home user, state this fact plainly in a bold header at the top of the setup section. You should also include: A parts list Unpacking instructions Warnings related to setup Results of an improper setup Who to call in case they encounter difficulty in setting up.

Provide information about operation. This section is the main portion of the user manual and should provide concrete, detailed information on how to use the device. Begin with basic preparation for using the device, such as plugging it in or washing your hands. Include graphics where necessary. Some steps are best explained with images as well as words. Think about using photographs or illustrations in your user manual.

In this section, as in every section, be sure to include relevant safety warnings about improper use or operation. For instance, you might warn users of a chainsaw not to drink alcohol or use the chainsaw while on certain medications.

If you think users would benefit, consider including links to online videos that demonstrate proper use and operation of the device. You could include these videos either at the beginning of this section, or in the case of videos that illustrate only one step at the end of each step. Try to keep your instructions as simple as possible.

If your manual gets too complicated, you might lose people along the way. Include a product summary at the end. The summary should go at the end of the manual, just before the index, in order to provide basic steps of operation.

This should be a simplified, stripped-down version of the operational information section, and should be no more than one page. Summarize how to use the device or product.

Include basic warnings, numbered step explaining how to use the product, and phone numbers or email addresses that direct users to help.