The idiots guide to writing help documents and manuals

If you have never written help documentation before then it can seem a little scary. The end-users of your product are relying on you to help them understand every function of the product, and their continued use of the product rests on how successful you are in providing answers to their questions. Here is our ‘idiots guide’ to writing manuals and help documents. These tips will help you write help documents that cover all the details you need to include and that can be easily understood by your end-users.

Understand your product-users

This is the most fundamental point in writing help documentation. If what you write is going to be useful to those trying to understand the product it must address the areas of concern that they have. There is no point writing a beautifully presented help manual if it doesn’t help anyone use the product, or if it answers questions that no-one is actually asking about the product.
Start by talking to those who use the product. Find out how they use it, what do they use it for? Which functions are the most commonly used? Talk to the help-desk or customer support, find out which questions users ask most frequently.
Once you have a solid understanding of how customers use your product then you will have a much clearer idea of which product functions you will need to spend your time explaining, and which areas can be passed over briefly.

Plan your table of contents carefully

It is important to include every function of your product, but it is even more important to make sure the guide is structured in a logical way. Users need to be able to find what they are looking for. A help guide is not something that most people want to read through from beginning to end. Most people only open the help guide when they have a specific question and they want to jump straight to the point in the help documentation that deals with that topic.
Try to think through each way your product will be used and list the steps in the order they will need to be completed to accomplish the required task, that makes it easy for readers to find the information they need.

Write for the correct audience

Write the manual or help documentation at a level that is appropriate for your product users. Think about who will be using your product and the amount of technical expertise they are likely to have. Good help documentation avoids assuming knowledge that the users don’t have, but it also avoids talking down to users and explaining everything in so much detail that they feel they are being treated like a nursery class.

Simplify the creation of your help documents

Use help authoring software to guide you as you create your manual. The easiest way to write good help documentation is to use software specifically designed to write that type of material. A help authoring package can make the job of laying out your documentation much simpler. With a topic editor, the ability to create templates, and a versatile media library included, designing help documentation is simple, and the completed manual can then be exported into a range of formats without the need to reformat the manual each time.

See also...

When help and manuals go wrong

Almost everyone has at least one help related horror story to tell. Whether it is about trying to understand a product when the help manual has been written in such poor English that it is …

Read More →

Best practice in writing help documents and manuals

Writing help documentation can be a tricky process. You need to learn to think like a product user not a developer. As the person responsible for writing the help documentation you may well have been …

Read More →

Why writing a quality help manual may be the best investment your business makes

Launching a new product takes both time and money, in any business both of these are generally in short supply. There are always pressures to reduce costs and get the product complete and ready for …

Read More →

Write better help documents in half the time

Writing help documentation can be a very long process. If you have a complicated product to explain it’s not unusual for them to be several hundred help pages, and even a fairly simple product may …

Read More →