Why I'd swap my spell checker for a better help API

If you are a technical writer worth your salt, you probably know your help content at least as well as your favorite novel. You've struggled over it for years, right?

But have you ever wondered how many of your help topics are actually read by users?

Scary question, I know. (Believe me, I know.)

The best content in the world is useless if nobody knows it exists.

Tracking tools aren't enough

Perhaps you've purged this inner worry by implementing server-side tracking software. Such server tools, often available from help authoring software vendors, can indeed tell you whether anyone reads your work. But statistics and user feedback may just confirm your fears; you still have to find a way to get more users viewing the help.

Embedded help vs. separate application

The root of this problem is the "help as a separate application" model of content delivery popularized by most help authoring tools. By separating instructional content from the application, we drastically reduce the chance of users actually seeing that content. We can't just assume everyone knows what the F1 key on their computer does.

Embedded help content would be a great solution. By putting help content, or links to relevant content, in the interface, more users are likely to find it. This is a wonderful option if the developers are willing to grant you some real estate in the interface. But we don't always have that luxury.

And that leads me to APIs.

Why APIs are the solution

Most professional help authoring tools provide a code interface that programmers can use to associate specific help topics with GUI elements. The API controls how the help is launched, including details like the size of the help window, where it appears on the screen, and so on.

Usually the API code is activated when a user presses F1 or CTRL+F1 from within a GUI element. This is where the plan falls apart. What if users haven't learned this convention?

Perhaps the APIs in help authoring tools could be modified so that when a GUI component has focus, especially for an extended period of time without user interaction, a help cue appears. This cue could be a simple prompt asking users if they need help, or even a hovering list of help links. Whatever the format is, it would need to balance being highly visible with being unobtrusive.

The key here is to ensure that this help cue is coded as part of a standard help authoring tool API, so that technical authors can ensure consistent help visibility regardless of the application.

If F1 and CTRL+F1 were marketing techniques, they would be the equivalent of sitting around waiting for customers to call and place an order. That isn't good enough. Your hard work deserves an API that can get content in front of users when they don't know how to ask for help.

Better APIs are the future of help.

See also: Building the next generation of help.