How to create a help API

by Tom Johnson on Mar 4, 2015
categories: technical-writing

In my last post in this series, I talked about static site generators as a platform for help. In this post, I want to explore Help APIs, which is actually something in part enabled by static site generators.

To put things in context, the web is sort of a giant API. Each browser functions as a client that accesses various resources from servers.

You may be viewing this post on my site. In this case, you used a client (a browser such as Chrome) and entered a URL (such as https://idratherbewriting.com/2015/03/04/how-to-create-a-help-api/) to make a request, and you got back a response (all the content on the page).

This cartoon from XKCD sums it up well:

Alternatively, you may be using a Feedreader, such as Inoreader. The feedreader makes a request to the server, gets a response, and shows the requested resource to you.

Changing paradigms for how we deliver help

The idea of me sending you a copy of this post as an attachment to an email is absurd -- and yet this is the same paradigm we sometimes have with help. We send developers help files to integrate into applications. We send users help files with products.

Here's an idea: we could just put help resources on our server and give developers an "endpoint" to access the site content.

Using the endpoint, developers could pull the help directly into the application. In fact, in some cases with small help files, you might not need a help site at all. You can just have a Help API that applications can call in order to get the information they need.

With larger projects, though, I doubt you can get away from having a dedicated help site. Still, there's a strong need to pull help into the user's context in an application.

The most common example: Tooltips

As probably the most common use case, let's say you want to add popovers/tooltips next to confusing fields. The developer can merely call the Help API for information related to that field. If you want to add a quick start tutorial, the developer can add a getting-started page in an application and call a Help API endpoint for the right information to populate that modal. And so on.

For a quick demo of how this might work, see the Tooltip Demo here.

By using a Help API, you can more fully integrate the help information into the application in all the right places where it should appear -- giving the user the right information at the right time in the right place.

Users generally dislike leaving the context of their work and going to another site, browsing through the external help site to find the right information. Few people actually consult the help, and even if people do go to the help site, finding the topic may be difficult.

But even if they find the topic, by now the user is so disconnected with the actual application and context of the problem that the help feels disconnected. Sure, the help may provide some screenshots, and in some scenarios, a video. But it's not quite the same as being in the context of the application where you encountered the problem, and where you must apply the knowledge to solve the problem.

Imagine how much better help would be if help appeared right in the place where you needed it, exactly when you needed it.

How to create a help API

I put the information for creating a help API using Jekyll as a platform here: Create a Help API.

Basically, you create a JSON file that loops through your tooltip content. Then you put it into a domain with cross-origin-resource-sharing (CORS) enabled.

Next: 2.0 Pushing content into any format with Jekyll