Hello World: Writing API Tutorials for Multiple Audiences

audiences

As technical writers, we understand where we fit in the world. No one wants to read the manual; they want to use the product. In fact, even that’s not true: often, users just want a certain result. This is especially the case with an application programming interface (API). External developers use an API because it offers them a specific result. Our job is to minimise the number of obstructions between the user and that target.

As with any code, good documentation explains how the API works so that the users can understand, use, and extend it. The usability of the documentation — whether it’s API reference material, in-code comments, or accompanying tutorials — has a critical effect on the overall user experience.

That’s a lot of responsibility. So how can we ensure that our API documentation lets the user get working as quickly as possible?

Understanding the Challenge

workstation

We’ve got a few things working in our favour. The user — let’s call her Emily — is an experienced developer. Emily is looking at this API because she has a concrete goal to work toward. She’s comfortable with technical details. And she’s happy to read code to see how everything works. (In fact, she sometimes prefers it.)

However, Emily has a junior colleague who’s less experienced: Theo. He will also use this API, and he’ll need more support.

The question, then: how can we structure the documentation so that it works for both developers, without overloading Emily with unnecessary information or, for Theo, assuming too much knowledge? We need to balance the usability for different audiences with different needs.

TWi faced this challenge in a recent API documentation project. Our client asked us to create a series of tutorials as part of a software development kit (SDK). We had to ensure that the tutorials enabled developers of all skill levels to quickly and easily get up to speed with the API.

Solving the Problem

working coders

Structure

The first task was to organise the raw content into chunks. We divided the content of each tutorial into sections, and broke each section into logical steps. For easier navigation in the finished HTML files, we mapped out an information structure and split the tutorials into separate files, with each section in a separate file.

We named each tutorial and section to indicate the expected outcome (for example, ‘Creating a selection from touch input’). This completed the first big job: when Emily and Theo start looking at this API, they can see what the API can do and judge whether it meets their requirements.

Navigation

We implemented a consistent navigation system that allows users to move easily through the tutorials. This system included introductions, prerequisites, and related links in each section to orient the user. We also added a document tree to the page navigation and breadcrumb links to move between sections in the active tutorial. Clear introductions and improved navigation, together with the task-based titles, make it easier for users to quickly scan the tutorials for the information they require.

Levels of Detail

With the names of tutorial sections as the highest level heading in each file, we inserted the steps as the next level of heading and formatted them consistently for emphasis. This allows a skilled user like Emily to quickly skim the material for the ‘what to do’ information. To help junior developers like Theo, we followed each step-level subheading with detailed instructions: the ‘how to do it’ information.

Emily can easily skip past information that she doesn’t need, saving her time and irritation. And we don’t exclude Theo by assuming knowledge he doesn’t have. Both developers can proceed at their own pace, at their own level.

Contextual Sample Code

The client provided long, complete blocks of sample code for each tutorial. In most tutorial steps, we used short snippets to highlight only the lines that relate to that step. Users like Theo can see the snippets building up, piece by piece, into a functional API call.

Emily doesn’t need the snippets, but she does want to make sure her own code matches up. We finished each section with the complete sample code so that both Emily and Theo can compare their work against it — catching a mistake when you finish a task is better than discovering a bug three sections later when something misbehaves inexplicably.

Related Information

Throughout the tutorials, we linked class names and other objects to the relevant API reference topics. This helps users to become familiar with the API components and gives them the option of digging deeper into the API. The consistency of these links makes it easier to hop back and forth between the references and tutorials as required.

Quality and Consistency

APIs can evolve quickly, resulting in changed or deprecated parts. This makes it difficult to keep the documentation up to date. We checked for obsolete method names, unclear steps, missing information, and outdated code samples. This quality check was critical. If a potential user can’t finish a tutorial, it’s a huge red flag that could drive them away.

Finally, we proposed writing conventions to help protect against similar errors creeping in down the line, to support future maintenance of the documentation by the client.

Achieving A Better User Experience

girl with book

On completion of the project, the client recognised that our work on the API tutorials made it much easier for developers to get started. This increases the chances of success: improving the on-boarding experience makes the API more usable, which increases the likelihood of adoption.

As we mentioned earlier, the job of a technical writer is to minimise the number of obstructions between the user and the desired result. Developers are happy to experiment to find their own solutions but they need the tools to do so. Well-structured, well-written API docs give them those tools, resulting in a better user experience all round.

If you’re writing API tutorials or other API documentation — whether API references, in-code documentation, or other types — how do you ensure the user experience is smooth? What other challenges do you face? Let us know in the comments below.

, , ,

2 Responses to Hello World: Writing API Tutorials for Multiple Audiences

  1. craig wright July 1, 2016 at 11:12 am #

    Good, sensible approach for all documentation where the audience has differing levels of knowledge.

    • Brian Lanigan July 1, 2016 at 12:14 pm #

      Thanks Craig, and I agree absolutely. It’s particularly relevant in the API space, since you have no idea who might try to use it. I’ve heard stories of people with no coding knowledge whatsoever hacking together functional API calls simply because the documentation and code samples were so good. They might not have understood it, but they could copy and paste enough pieces to get the result!

Leave a Reply

Top