How to write user manual for application

To be truthful, manuals do take time to write, but clients are always appreciative to have them. For projects that include a user manual, I go so far as to write the manual before the software! That way, the manual does triple-duty additionally acting as a scope-of-work document and as a to-do list.

It is ideal for generating documentation for FileMaker or other database projects. I found engaging in the process of generating manuals actually helps me to improve my software. If I am working through explaining how the software works in ScreenSteps and it seems to me too complicated, I will usually make an effort to simplify my software.

Great feedback from you two! Because I am not a developer, it's really great to hear how developers like to approach user manuals. Your email address will not be published. Save my name, email, and website in this browser for the next time I comment.

Who will be the primary user of the application? How many people will be using the application? This distracts the user from finding the information they actually need. Users usually consult the instruction manual because they want to get something done or solve a problem they are facing: They want to install the latest version of their anti-virus software, bake bread or find the meaning of the flashing warning light on top of their machinery.

Knowing your user helps you to write more consistently. It helps you select the correct information and to focus on the tasks that your user wants to complete. This may seem like common sense, but knowledge really is the key to writing instructions that really help your users. For example, when writing the user instructions for a camera, knowing how the shutter speed and aperture interact with each other, makes it much easier for you to describe each function as it relates to the whole.

It is the task of the technical communicator to share technical information clearly with the user of a product. Technical education, background, experience and communication skills will help each technical communicator do this successfully. The best way to do this is by using the product yourself: try to install it, push the buttons, open lids, identify signals etc.

Always take your own safety into account! Possibly there is already some information available, such as existing instruction manuals, a risk analysis or marketing information. Study this information and go through the full product life cycle, from purchasing to disposal, in your head. A hands-on approach trying the product yourself , will give you a feel for what sort of information needs to be communicated to the user.

When things are unclear, look for information on the internet or in existing, similar user manuals. Other product manuals can show you how other technical writers have found solutions for similar problems. But be careful…. Be critical and only consider information that you fully understand and can validate. Also, existing material might not always be as clear. Often you find a lack of structure, inconsistency or vague instructions.

We will discuss that later. Your product may or may not include all the functions that you find in existing material. Identify the differences. What makes your product unique? What functions are identical? What information can you use for a better understanding of your own product? When you slowly build up a complete picture of your own product, questions will arise.

Not everything will be clear after your research. Make sure to note down any unclarities. These will be solved in the next stage. The best way to have your questions answered is by talking to knowledgeable people that know the product best. We call them subject-matter experts SMEs. An SME is a person with a deep understanding of a particular domain which can be a job or topic. SMEs can be mechanical, industrial design, software or electrical engineers. They can be helpdesk support staff, maintenance personnel or installers.

But also managers, scientific researchers, testers, dealers or business owners might have the in-depth knowledge of the subject that you are writing about and be the subject-matter expert you are looking for.

Make sure to do your homework well. Study your topic thoroughly and prepare a list of clear questions. Gather all your questions together and make an appointment. As SMEs are valuable to a company because of their knowledge.

They are also busy people. Take this into account when you are interviewing them. Most technical SMEs are more comfortable in the world of numbers, processes and technical principles than words. They are more into getting things done and getting results than communicating about how to get these things done. They might use a lot of jargon. All those numbers, technical terms etc. Do not force your SME to avoid jargon. It is your job as a technical communicator to ask the right questions about the meaning of terms and to decide what information to use.

Make sure that they feel comfortable and appreciated for their knowledge and valuable information. Make sure that the answers to your questions cannot be found in existing material, to prevent losing your credibility in the eyes of a sharp engineer. The best way of interviewing an SME is in person. Alternatively, you can do it with a phone call. Sometimes you will be asked to put your questions into an email or spread sheet. My experience is that this will delay a project: Answers to questions will lead to new questions.

It is your task to keep on asking questions until you understand every bit. Make sure to record your interview. I always use my mobile phone to make videos of all my interviews and when we discuss the full functioning of a product. This will prevent you from asking questions during a second interview or writing down nonsense in the eyes of your SME. For example: during an interview, SMEs will automatically mention the right names for product elements.

You might not remember all of this, but when looking back at your material, you can get out all of this information. This prevents a lot of frustration. Also, ask SMEs to review your work. Their knowledge and feedback is of vital importance for writing clear information for use.

This is the starting point for both interviewing the SMEs and the mapping, structuring and organising your information see next sections. The user s you are writing for might encounter problems during the life cycle of the product. They want to solve these problems. And that's where they need you for. So when talking to SMEs , gathering information, etc.

Typical problems are similar to the above described questions and have to do with the installation, use, maintenance, repair, cleaning and disposal of the product. In that case you can break it down into chunks. For example, for a type of machinery, called the Roof Washer, we created an instruction manual. One of the main steps that needs to be taken by the user is making the Roof Washer ready for use.

You are already starting to create topics now. Topic-based authoring is essential for writing clear instructions. You are overwhelming yourself with information: from using the product and analysing all available documentation, to the information you get from the experts. This information consists of a description of the problems your users would like to solve, to solutions on how to solve them, but also all kinds of other information such as electrical schemes, spare part lists etc.

One of the most challenging tasks of a technical writer is to gather all the information, analyse it, determine what is relevant, delete information, organise and structure it. This is fairly impossible without mapping out your information.

These topics will be clearly organised and identifiable in your table of contents or menu structure, following the life cycle of your product see next section. But before you will have your final, well crafted yes, this should be your masterpiece table of contents, you would like to structure and organise all information. Example of a mindmap. One single topic gives the answer to a single question a user has.

Users want to solve one problem at a time, not multiple. That confuses them. Each topic will have a place in the user manual. A topic can become a chapter or a sub- paragraph. Or maybe a topic fits better in another guide that needs to be created.

The standard for the preparation of Information for Use , structures information around information types and information products. Another way of visualising the relationship between information types, such as topics and instructions, is by means of the following model:.

The information can be structured around several information products that are selected, presented, and delivered in different media to meet the needs of different target audiences. A user manual or instruction manual is one type of information product.

Other types are installation manuals, maintenance manuals, online help etc. A user manual, when printed, is an entire paper booklet describing how to use a certain product. The user manual, installation manual and quick start guide of a product. A topic can be conceptual e. If a topic is complex, it may contain several chunks, indicated as instructions in the above information type model.

Instructions are basically subtopics. A step is a detailed description within an instruction. Instructions contain several steps. Together they describe the step-by-step process of performing a given task. Each instruction has a clear goal, which should always be task-oriented and to the point principles of minimalism. Each step is task-oriented and enhanced with illustrations. The user follows these steps by reading through the instructions. You will find more about how to write instructions in the next chapter.

Try not to use more than steps when you want your instructions to be effective. Use steps when you want users to memorise a task. 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.

It is of crucial importance to format and present information types such as warnings, steps, error recognition, tips, consistently at all times. Consistent formatting will support users identifying the information they are looking for. For example, clear formatting of a safety warning draws more attention to the safety message as the user visually recognises it as being a safety message.

We have discussed several methods and models that will help you map out, structure and organise information. There is not one single way that works best, but I think a combination of the above mentioned techniques, with some good theoretical background, is the way to write clear user guides. One last thing I would like to discuss is the similarity that I found between the information development process and the product development process.

The process of gathering and structuring information is quite similar to this model that I was taught at university, which is used for innovation processes. At the left, the model describes the basic design cycle. It starts with a description of the function that a product or service needs to fulfill. After a broad analysis of strengths, opportunities, weaknesses and threats, you are able to draw up your criteria list of requirements.

The right model describes the process of researching, idea generation, concept creation and realisation. Each of these stages are characterised by a process of divergence and convergence. You first gather many alternatives before selecting the best ones. When I apply this model to the process of creating user instructions, it would look like the following:. 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. It should be a well thought-over piece of art. The ToC is the spine of your user manual! When your users are facing a problem and they want to consult the user guide to find an answer, they will most likely go to the table of contents to see where they can find that answer.

A clear table of contents helps the user to navigate to the right instructions, without having to frantically search through the entire instruction manual.

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. Our documentation is getting far more views and longer visits than it ever did in the old format.

Manula seamlessly integrates into our website, using our custom colors and logos to give a consistent user experience. The layout, table of contents, fonts and tables are inviting and easy on the eyes. We can even hide minor topics from the table of contents, thus keeping our extensive help from appearing too intimidating.

I love the ease of updating, the change control system, and ability to support multiple versions. And because the help is online, I can fix a typo or add a new topic any day of the year.

This means there is no longer a rush to get the help finished weeks before an upcoming release. The context help is extremely easy to implement on both my end and the developer end. We are super happy Manula customers and would recommend it to anyone! An example of our help can be seen here.