[Guest Post] “Setting the Help Hooks: Context Sensitive Help Using RoboHelp”, by Neil Perlin

Help maven, Neil Perlin, is delivering a 3-part webinar series on Advanced RoboHelp. This is the first of three guest posts by Neil that summarize his guest webinars. You can find the links to the other two at the end of this blog post.

This blog post covers highlights of our webinar with Neil Perlin: “Setting the Help Hooks: Context Sensitive Help Using RoboHelp.”

_________________________

Welcome to the first of three blog posts dealing with questions that I often hear about Adobe RoboHelp, typically “Can RoboHelp do such and such?” In this post, I’ll look at context-sensitive help – what it is and whether and how RoboHelp can create it.

Basic Definition

Context sensitive help (“CSH”) is help that’s sensitive to the context in which it’s invoked – e.g. the help system in an application knows what users are doing when they ask for help and displays only the help that’s appropriate. For example, if you’re on the Print dialog box and click the Help button, you’ll see the help specifically for the Print dialog box; you won’t have the entire help system thrown at you and have to find the desired topic on your own. As simple as that.

CSH “Design”

“Design” refers to the level at which CSH is provided. It’s usually large scale, such as for screens or dialog boxes, or small scale, such as for screen objects like a field. How do you choose?

The small scale design seems to make sense because of its granularity. If each field has its own individual help, there’s no wading through irrelevant material like you’d find if there was one help topic for a dialog box that had multiple fields.

However, the small scale option suffers from the conflicting problems of completeness versus silliness. In other words, completeness would demand having a help topic for every field on a dialog box even if some of those fields are so obvious that any help topic for them would be silly – e.g. “Type your name here” (in a Name field). However, fields that seem obvious are not. Consider a Zip Code field on a User Information dialog box. We don’t need help about the format of a zip code. But what if the software was being used in Canada, where they use Postal Codes. The Zip code format may be unfamiliar and require help.

The large scale model is less granular than the small-scale model but it eliminates many problems of the small-scale model. It creates one CSH topic per screen or dialog box, typically accessed by clicking a Help button, so there’s less clutter on the screen. There’s also less work for the programmers. And the large scale model translates neatly onto the web.

My recommendation to most of my clients is to use the large scale model. But I advise them to see what their competitors are doing with CSH, with the caveat that just because their competitors may be doing something doesn’t make it right. (Think of your mother saying “just because all your little friends are creating field level CSH doesn’t make it right”.)

How to Create CSH for a RoboHelp Project, Using RoboHelp

Can RoboHelp create CSH? Absolutely. It’s been able to do so almost since it appeared in 1991. Why the odd wording of the section title? Because today, you can create CSH for a RoboHelp project by using any proprietary method that your programmers come up with or by using either of two methods supported within the RoboHelp interface. The proprietary methods are so different as to be impossible to sum up in one post. Talk to your programmers and document the process.

There are two approaches through the interface – the map file/alias file model and the link model. Both basically do the same thing – open a help topic associated with a specific dialog box or screen and open the navigation panes – the toolbar and the ToC, Index, and Search tabs – around that topic. What makes the two models different is their mechanics, who does what work, and whether the navigation panes open automatically or manually. Watch the recording of the webinar for an explanation of how the two models work. Here, I’ll just sum them up.

Map/Alias File:

• Navigation panes open automatically.
• The use of aliases in the coding provides more programmatic flexibility than the link model.
• But the use of aliases in the coding means more work for the help authors, who have to create the map and alias files, and the programmers, who have to create and embed map #s in the application screens.

Link:

• Navigation panes open when the user clicks on a “Show me the navigation panes” link.
• The hard-coded paths from the Help buttons in the dialog boxes to the appropriate HTM files means less programmatic flexibility than the map/alias file model.
• But the help authors’ ability to turn on the link feature with a single mouse click in RoboHelp means that the programmers effectively do all the work.

Summary

Creating CSH is one of the most tedious tasks in help authoring, and it must be done correctly. If it’s not, the result can be a Help button that doesn’t work or, worse, opens the wrong help. RoboHelp provides various options for CSH creation depending on your technical needs and development resources and goes far to make the work less tedious.

See also the other two parts of this Series from Neil Perlin:

• Part 2: Single Sourcing With RoboHelp
• Part 3: Like Beads on a String: Structured, Topic-Based Authoring in RoboHelp