5 mistakes to avoid when writing help documentation

How often have you spent ages searching a help file for something that you know should be there, but you just can’t find? Help documentation is usually the first place that we look when we don’t know how something is supposed to work. If the information in the help file is not clear, or even worse misleading then we are just going to end up frustrated, and maybe even rejecting the product for something easier to understand.

Not writing the table of contents first

If you are writing help documentation it needs to thoroughly explain every aspect of your product. It is important not to forget about any features that your end-user may need to know about. The easiest way to make sure you cover everything properly is to start with a plan. Write your contents page at the start and list there every topic that you need to write about. This way you can be sure that nothing gets left out.

Assuming knowledge the user doesn’t have

One of the problems with a lot of help documentation is that it assumes everyone comes to the product with the same level of knowledge. Often the documentation is written with one particular type of customer in mind when in reality there are many types of people using the product, all with different levels of knowledge. The best help documentation explains every procedure clearly from the start and doesn’t rely on users already knowing anything.

Not updating the help documents

Help documentation that is not updated when the product changes is often worse than useless. There is nothing worse than trying to follow instructions, only to be told to press a button which now doesn’t exist. Using a good help authoring software can save a lot of time in this situation. HelpNDoc, and similar programs makes it easy to edit your help file index, and rewrite or move around sections of your text without having to redesign your entire document every time you make changes.

Not having a proper index

When a user comes to your help document with a problem where is the first place they will look? In many cases they won’t start at the front and work their way through to the end of the document. They will start with the index and look up what is said about their problem. The index is a vital tool in all help documents, make sure it is as complete as possible. Including synonyms in the index is an excellent idea, there is often more than one word that can be used to describe a topic, so make it easy to find out what the user wants to know.

Not letting anyone else check or edit your work

Even if you think you can produce the greatest help documentation in the world, it is always worth getting someone else to read it through and suggest changes. Everyone has different ways of approaching a subject and it is likely that a fresh pair of eyes will be able to pick on areas that could be improved and made clearer.

Avoiding these five common mistakes will improve the quality of your help documentation, and improve the experience of your product users. Writing good help documentation makes it more likely that users will persevere with your product, and ultimately builds a stronger, more loyal customer base for your products.

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 →