Software manual writing

As a result, the guide may make assumptions about the reader's skill level that are often incorrect. The first step in writing a good user manual is to get the actual writing process as far away from the engineers as possible.

The software developer knows more than anybody what makes the software work, but that doesn't mean the developer should write the guide. On the contrary, it is a distinct disadvantage. More important than a deep understanding of the inner workings of the software is an understanding of who the end user will be, what his educational level is, and how that end user will be using the software.

In most cases, end users don't need to know the finer points of programming and the back-end workings of the software -- they just need to know how to use it to make their jobs easier.

The user manual should be largely task-oriented, rather than heavily descriptive. Because the manual is written to help users understand how to execute specific tasks, the writer needs to have an understanding of those tasks as well, and as a result, going through each discrete step of each feature is absolutely essential.

It's not necessary for the writer to necessarily know how the program was created from a design or development viewpoint, but it is essential to have a strong working knowledge of all its features. While executing each task, take time to write down each and every step, including clicks, drop-down menus, and other actions. 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.

But how do you know which error information to include? 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: Seeing the problem; Expressing the problem; Processing the problem-solving information. Additionally, good error management makes learning to use a product more productive. I discuss this in more detail in this podcast : Pay attention to the safety instructions and support safe use Safety is my favourite topic.

There is a solution to this that meets in the middle! First I would like to explain why we include warnings in user manuals. 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. As a rule of thumb you should warn where the risk is most likely to occur.

As the name suggests, section safety messages are placed at the beginning of a specific section. When it comes to usability, you can do two things here. First of all, you could sum up all safety warnings that relate to that specific section. A more user-friendly approach would be: 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. A good warning consists of three parts: The type and source of hazard; The consequences in the event of non-compliance; Measures to avoid the hazard.

A warning is preceded by the signal word danger, warning, caution or notice. WARNING Signal word used to indicate a potentially hazardous situation which, if not avoided, could result in death or serious injury Indicates a hazardous situation that, if not avoided, could result in death or serious injury.

CAUTION Signal word used to indicate a potentially hazardous situation which, if not avoided, could result in minor or moderate injury Indicates a hazardous situation that, if not avoided, could result in minor or moderate injury. Avoid legal pitfalls and make your instruction manual legally compliant 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 videos explain excatly how to create a compliant manual for electrical equipment How to use the Operator Manual Template for to create a machinery manual: And for medical devices TO THE STORE Add navigation to optimise your user guide for findability An essential part of a clear user manual is the way your user can navigate to the information they are looking for.

The order of the topics largely determines how quick users find what they are looking for. 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.

Make sure that the index includes synonyms that are most likely used. Example of an index A glossary is an alphabetical list of words relating to the specific subject you are writing about, with explanations. Example of a glossary Another glossary example Review your user manual to get rid of errors, pt. Use their feedback to optimise the instruction manual.

All of these serve a different purpose. Use illustrations to enhance text 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.

Illustrations to describe a sequence of steps When you place illustrations as close as possible to the text to which they relate, it is clear to which textual instruction they belong. Illustration that identifies main product parts Sometimes photos are used instead of illustrations. Use of a photo in a user manual that our client created Use of an illustration in the new instruction manual the we created When creating illustrations, you can leave out irrelevant information or easily emphasise important information.

Screenshot with an overview of main functionalities Explanation of the use of an app in a user guide Use tables to organise data You can use tables to organise numeric or verbal data. Technical data presented in a table Consider using video instead of illustrations Video or animation can serve many purposes.

Example of a realistic video tutorial Example of a 3D animation Example of an explainer video in cartoon style When using video, synchronised spoken or written text, or both, can be used to accompany the sequences. Use interactive animations to increase effectiveness and efficiency Another increasingly important form of animation, is interactive animation.

Example of an online interactive animation according to minimalism principles Keep in mind that, as video might require a stable internet connection, it is less suitable in areas with bad reception.

Use symbols if you want to communicate language-independently 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 independently of language.

Some programming languages, such as Java and the. NET, C , have their own standards for documenting code. In these cases, follow the standards as to how much of the documentation should be included with the source code.

Choose the appropriate documentation tool. In other cases, the tool to use is determined by the type of documentation required. Word-processing programs for Microsoft Word are adequate for creating separate text files of documentation, as long as the documentation is fairly short and simple. For long, complex text files, many technical writers prefer a documentation tool such as Adobe FrameMaker.

Method 2. Determine the business reasons for your documentation. Although the functional reason for documenting software is to help users understand how to use the application, there are other reasons as well, such as assisting in marketing the software, enhancing the company image, and most notably, reducing technical support costs. In no case, however, should software documentation substitute for poor interface design.

If an application screen requires reams of documentation to explain it, better to change the screen design to something more intuitive. Understand the audience you're writing the documentation for. In most cases, software users have little knowledge of computers outside of the applications they use.

There are several ways to determine how to address their needs with your documentation. Look at the job titles your prospective users hold. A system administrator is likely expert with a number of software applications, while a data entry clerk is more likely to know only the application he or she currently uses to enter data. Look at the users themselves. Although job titles generally indicate what people do, there can be considerable variation in how certain titles are used within a given organization.

By interviewing prospective users, you can get a feel for whether your impressions of what their job title indicates are accurate or not. Look at existing documentation. Documentation for previous versions of software, as well as functional specifications, provide some indication as to what the user will need to know to use the program. Keep in mind, however, that end users are not as interested in how the program works as they are in what it can do for them.

Identify the tasks needed to do the job, and what tasks need to be done before those tasks can be done. Determine the appropriate format s for the documentation. Software documentation can be structured in 1 of 2 formats, the reference manual and the user guide. Sometimes, a combination of formats is the best approach. A reference manual format is devoted to explaining the individual features of a software application button, tab, field, and dialog box and how they work.

Many help files are written in this format, particularly context-sensitive help that displays a relevant topic whenever a user clicks the Help button on a particular screen.

User guides are often formatted as printed guides or PDFs, although some help files include topics on how to perform particular tasks. These help topics are usually not context-sensitive, although they may be hyperlinked to from topics that are. User guides often take the form of tutorials, with a summary of the tasks to be performed in the introduction and instructions given in numbered steps.

Decide what form s the documentation should take. Software documentation for end users can take 1 or several of many forms: printed manuals, PDF documents, help files, or online help.

Each form is designed to show the user how to use each of the program's functions, whether in the form of a walkthrough or a tutorial; in the case of help files and online help, this may include demonstration videos as well as text and still graphics. Help files and online help should be indexed and keyword-searchable to allow users to quickly find the information they're looking for.

Although help file authoring tools can generate indexes automatically, it is often better to create the index manually, using terms users are likely to search for.