Some Best Practices When Writing Help Documentation

Some Best Practices When Writing Help Documentation

If you are planning to create online help documentation and want to make sure you end up with one that is truly helpful, here are three best practices you can follow to make sure it is:

  • Tailor it to users who have with varying skill sets and goals.
  • Review, test, and update it for accuracy.
  • Create context-sensitive topics.

Keep different users in mind

You can’t always predict what every user will know or want to know about any product. On one hand, if you oversimplify help steps, users might get confused. If you provide too much detail, they might get frustrated or bored.

One way to alleviate this problem is to divide help topics into several different types that target users at different skill levels by varying the kind and amount of information you provide. For example, you might have an overview topic, such as a definition of a specific system function, and then provide a link to all of the tasks related to that function within the overview. That way, users get just the specific steps they want.

The key is to allow users to navigate the help documentation to find (or avoid) as much detail as they want.

Review and revisit the help topics

You might not be able to wait until you have complete information about a product before beginning to write its help topic. Often, they are developed simultaneously. So any time a product is modified, the online help documentation should be reviewed to make sure the task steps are correct, terms are still accurate, and that nothing has been overlooked.

After a product has been released, users might discover faster, more efficient, or preferred ways of performing tasks. Also, storing help documents in a repository like SharePoint can promote ongoing evolution and expansion. It’s important to revisit the help documentation to strengthen and/or expand it with your own first-hand product knowledge.

Provide context-sensitive help topics

Context-sensitive help directs users to the topics they will most likely need help the most. For example, if users are looking at a screen and suddenly get confused about a term, button, or function, context-sensitive help will display topics from the help menu according to their current location. This will eliminate the need to start from a main menu and navigate from there. If a topic isn’t what they’re looking for, they can still search through the other topics. In addition, you can add a table of contents so if users search for a topic that’s completely unrelated to their location within the application, they will be able to browse for other topics as well.

What works for one user may not work for others. These three tips should help you write or edit material that is accurate and reaches the greatest audience. For one, you give users an organized, easy-to-understand method for finding specific, detailed information. You also make sure that the information you give them is accurate to begin with and stays that way. And, you can make it easier for users to get the right information at the right time and place.

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*