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 involved with your product for a while, and have become very familiar with how it works. This is useful when writing help documentation but it can also be a disadvantage as you approach the product in a different way to those looking at it for the first time. What may be obvious to you may be a complete mystery to someone without your prior experience of the product, or knowledge of the design process.

What are the best practice in writing help documents?

Very few people open a help document at the beginning and read through it to the end. Most people open help documentation when they want to know one particular thing. Often there is a function, or a tool that they want to use, and they can’t understand it without one specific piece of information. They want to be able to open the help manual and quickly locate information they need and then get back to work as soon as possible.

There are some specific things we can say about the way help documentation needs to be arranged:

• Help documentation must be arranged logically
• Help documentation must designed so that it is easy to scan
• Help documentation must come with a topical index

Arrange the help document logically

The best practice in writing help documents is to arrange all material by topic. Users will generally understand most things they need to know to make your product work, but there will be a few areas where they will need some help. As a technical author it is your job to write the documentation in such a way that they can easily locate those topics they need help understanding.

Design the help documentation to be read quickly

The best help documentation is always easy to scan. Users need to be able to pick out the section on the page which contains the information they need. They don’t want to read an entire chapter of closely typed text telling them information they already know. Break down the text into short, easy to read paragraphs and make it clear what each section is about.

Remember to include a good index

The index is probably the most important part of any help documentation. Unlike a conventional book many readers will turn to the index before they read any other part of the book. The index should be as complete as possible, and should list every topic that your readers may search for. It is also an excellent idea to include synonyms of topics.

How can you conform to these best practices in writing help documents?

Writing help documents in this way might sound like hard work but there are authoring tools available to help make the process simple. HelpNDoc is an example of free software which does all the hard work for you. This package includes keyword editors, and topic editors to make arranging your work simple, and when you have completed all the writing your document is automatically converted into multiple formats with no extra work.

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 →

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 →

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 …

Read More →