How to Create Truly Context Sensitive Help

Context sensitive help is a leap of effectiveness for user help and product documentation: it provides on-page help, allowing the user to stay in-app, instead of wandering away to another tab/window and breaking her concentration by leaving “the zone”. Today, any competent technical communicator can create context sensitive help with a little help from developer from the R&D team.


The DIY options for creating CSH are here, but they are not perfect. We wrote a 5-step guide, with some of the process’ shortcomings, so you know where you stand when approaching the operation:


  1. Create a map file
  2. Write the help topics outlined in the map file
  3. Integrate the context sensitive help into the code base
  4. Publish the help topics
  5. Test


Let’s dig a little into each and every one of these steps:

1.     Create a Map File

Traditional context sensitive help solutions all treat the product as a set of visual elements (button, text field, dialog box, window, etc.). In this step of the process all the stakeholders go over all visual elements in the application and map them. Each element is provided with a textual ID and a unique number. The output of this step is a textual file with lines as follows:


  • #define ID_PremissionDialog 101
  • ID_PremissionDialog is the help topic id – this will be used by the technical writer in the help authoring tool.
  • 101 – also called the map number, it will be used by the developer when integrating the context sensitive help into the code base (step #4).


The purpose of the map file is to create a contract between the technical writer and the developer. As soon as the map file is created the developer can go on to write code and the technical writer can write the help topics. If all goes according to plan, they won’t need to interact again about it – unless they really want to 🙂

Obstacle: Applying Context

When it comes down to it, all help authoring tools define the context as the visual element (and the page it which it is contained). In order to create truly contextual help we must take into account a major factor that is currently overlooked in most implementations – the user.


Other questions we must take into account for help to be truly contextual:

  • Is this the first, second, or tenth time the user reached this page? If it is their first time, we might want to automatically show a lightbox and provide an overview of this page. On the tenth time, we might want to point out some of the more advanced settings.
  • How did the user get to this page? If I try to create a new contact in a CRM immediately after creating an opportunity I will probably want to know how to link the two.


2.    Write Help Topics

Once the map file is created, the technical communicator knows the identifier of each visual element in the application for which help is required. He can then write the help topics with a help authoring tool of choice.


In a perfect world, this is the only step that the technical communicator will ever need to do. Incidentally, this is also what a technical communicator should love to do.


3.    Update the Code

On a different floor of the company building, the developer is now free to add the code related to the context sensitive help into the application/product.

For each help topic, s/he must add JavaScript code to launch the contextual help.


  • For Adobe Robohelp

RH_ShowHelp(0, “context-WebHelp/startpage.htm>Mainwindow”, HH_HELP_CONTEXT, 101)

  • For Madcap Flare

MadCap.OpenHelp(101, null, null, null );

Notice the matching parameter, 101, this is our map number from map file in step #1

Obstacle: Adding a New Help Topic

Consider the following use case: you have released a new version of your product with shiny new contextual help. After a month or so in production you identify a recurring question about a certain form field. Back when you sat with the developer to create the map file you both felt this field was trivial. So you want to do the only reasonable thing – create a new help topic. You can’t, you need to wait for a developer and go back to step #1. At best this new help topic will be rolled to production on the next release – several months from today 🙁


Adobe Robohelp has identified this problem and they now support dynamic editing of context-sensitive topics. Unfortunately, this option is not yet supported for web products.


4.    Publish Help Topics

After the help topics are ready for production, the technical communicator can publish them. This is a critical step in the process as it allows you to make revisions in your content.


Why is this important? Often, while a certain help topic is live in production, you will want to update it with some new information about the next product release. You wouldn’t want your new content to go live until the new release is up and running.


5.    Test

After everything is ready and the new version is released with all the help topics, you will need to test them. This is an important aspect of user experience, to make sure users are being served the help that they need, when they need it. If there is even a minor glitch or error in the help display, all your (and the developer’s) hard work has been for nothing.



Eyal Lewinsohn is the CEO of Iridize. Eyal has been developing software for almost 20 year now, having led R&D teams when dinosaurs were still walking the earth. Eyal is a true believer in making the digital world accessible to all, and in the power of good onboarding to do that. Eyal holds an MBA from Tel Aviv University, is happily married and father to 3 kids and a dog.