<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=1843331519326053&amp;ev=PageView&amp;noscript=1">

Sagitec Blog

3 Best Practices for Writing Online Help Documentation


Online help documentation isn't usually a priority when buying or building software systems, which is why it's rarely as helpful as it could (or should) be. To ensure your online help system actually helps end users, follow these three best practices.

Online HelpWhen you’re working in a software program and get stuck, where do you turn for help? Chances are your go-to resource is the great and powerful Google--and I don't blame you. The internet is packed with helpful resources and forums regarding (just about) any commercially available software application in use today, including Microsoft Office, Adobe CreativeSuite, and countless others. But what happens when the program you need help with is a custom enterprise business solution...maybe a pension administration system or a financial management system? Google won't know Jack about that. I'm afraid the help menu is your only hope.

Sadly, online help has garnered a reputation over the years for being as useful as a kickstand on a submarine. There are many reasons for this, which we needn’t go into here (for the record, it isn’t all Clippy’s fault.) Suffice it to say that help systems don’t always benefit from the same thoughtfulness, time, and resources used to develop those applications they’re paired with. If you’re planning to purchase, use, or create an online help system and want to make sure you end up with a system that is truly helpful, make sure that it is:

  • Tailored to users with varying skillsets and goals.
  • Routinely reviewed, tested, and updated for accuracy.
  • Context-sensitive.

1.   Tailored to Fit

A common problem with help systems is that they don’t account for disparities in users’ skills or objectives. It’s understandably difficult (if not impossible) for a technical writer to predict what a user will or will not know prior to using the system—not to mention what they’ll want to know. Writers must use their best judgment. But oversimplify help steps, and the audience gets confused. Provide too much detail, they get bored, frustrated, and log off.

So what to do? One way to alleviate this problem is to divide help topics into several different ‘types,’ targeting users at different skill levels and varying both the kinds and amounts of information presented.  For example, an effective help system might start from a high level, providing an ‘overview’ topic (i.e., a definition of a specific system function) and therein list all of the ‘tasks’ related to that function, as seen below.


Processing Person Records


Person records are created and maintained for individuals that interact with the pension fund and/or the system (e.g., plan members, retirees, and beneficiaries). Person records contain demographic and contact information and, when applicable, link to other details regarding retirement applications, plan information, associated organizations, etc.

Related Tasks:

  • Create New Person Record
  • Edit Person Record
  • Delete Person Record
  • Create New Contact
  • Process Benefit Estimate
  • Process Retirement
  • Create Payee Account


In our example, the overview topic gives the user general information and then allows him/her to ‘drill down’ into more detailed information as needed. If, for example, the user wants to know the specific steps for creating a person record, he or she can click on that topic and get those (and only those) specific steps, as such:


Create a New Person Record:

a)       Select Person > New.

b)       The system displays the Person Details screen.

c)       Enter required demographics data:

  • Name
  • Date of Birth
  • Address
  • Phone Number

d)       Click the Save button.

The key here is that information is presented in an organized, easy-to-digest fashion. It enables the user to navigate the system to seek out (or avoid) as much detail as he or she desires.

2.   Reviewed & Revisited

Help authors do not always (if ever) have the luxury of waiting until an IT solution is complete before beginning to write its help documentation. Often, the two are developed concurrently. Of course, this creates obvious problems. Any time the software system is modified, help documentation must be reviewed to ensure that task steps remain correct, terms are still accurate, that nothing has been overlooked. Remember, many IT solutions are modified or updated years after their initial implementation, meaning businesses must be diligent and assume responsibility for keeping their own help documentation current. This can be difficult or even impossible depending on how the help documentation was originally created and where it is stored. Software vendors take note: you’ll make life easier for your clients by creating help systems in open-source programs that can be acquired and used with little cost or additional training.

Also, storing help documents in a repository like SharePoint can promote ongoing evolution and expansion. After a system is implemented, end users may discover faster, more efficient, or just preferred ways of performing their job duties. Organizations should encourage staff members to revisit help documentation over time, to strengthen and expand it with their own first-hand system knowledge.

3.   Context-Sensitive Help—Providing Help Where It’s Needed Most

What I mean by ‘context-sensitive help’ is an online help system that saves time by directing you to the topics you must likely need help with. It works like this: Say you’re visiting a given screen in your company’s system when suddenly you find yourself confused about a term, button, or function. If you were to click on the help menu from that screen, a context-sensitive system would display help topics according to your current location, in an attempt to avoid the time and effort needed to start from a main menu and navigate from there. If the topic isn’t what you’re looking for, you still have the option to search through the entire help directory.   

Online Help Documentation

To illustrate this point, we've provided an example of context-sensitive help documentation below. As you can see, the user is currently located in the Person Maintenance area of the application (first image on the right). The system has displayed a help topic for managing a person's record based on the user's current location (second image, below on the right). For added benefit, the help documentation has a table of contents too. So, if the user searches for a topic that’s completely unrelated to their location within the application, they will be able to browse for other topics as well.

It’s difficult to write a catch-all, indisputable how-to guide for writing effective software help documentation. What works for one user may not work for the other. But the three aspects we’ve discussed in this post are as close to sure-fire bets as you’re likely to find. For one, you give users an organized, easy-to-understand method for finding specific, detailed information. You make sure that the information you present them is accurate to begin with and stays that way. And, you try to make their lives easier by giving them the right information at the right time and place. If you try all that and it’s still not working, hand out free donuts.

What has your own experience with online help been like? Love it/hate it? Can you offer any other tips for ensuring a helpful online help system?

Please let us know in the comments below.


Are you considering a new line-of-business solution? Take our free pension system assessment and receive a customized report that contains an evaluation of your current pension administrative software along with key recommendations for improvement. 

Learn More

About Sagitec Solutions:

Sagitec Solutions, LLC designs and delivers tailor-made pension, provident fund, and unemployment insurance software solutions to clients of all sizes. Sagitec has the expertise necessary to help their clients achieve strategic business objectives, enhance service offerings, and lower operating costs. Find further information by visiting http://www.sagitec.com. For more information, contact Rick Deshler at (651) 335-3406 or at rick.deshler@Sagitec.com.

Topics: Software Development, Software Documentation