Make your API docs pop with an Interactive Tutorial

As a developer, one of my favorite API doc sites is Algolia’s. There are many things to complement including the beautiful design, clear organization, and concise writing.

My favorite thing, though, is the interactive tutorial that they include as part of their quickstart guide.

This is a live, browser-based coding exercise that allows developers to get a hands-on experience of Algolia’s API without having to set up or install anything.

Algolia’s Interactive Tutorial

Inspired by this, I decided to create an interactive tutorial of my own. Thanks to new in-browser coding tools like Code Sandbox and Stackblitz, it was easier than I first thought.

Similar to Algolia’s, the interface I built provides instructions to the developer on the left side of the page and a live coding environment on the right side of the page.

You can try it here.

In this article, I’ll explain the approach I took to build it and how you and your team can create an interactive tutorial to showcase your own API or library.

If you’re looking for advice or assistance in creating an interactive tutorial feel free to get in touch with me here.

Overview

An interactive tutorial is essentially a frontend app. I built mine with Vue. The main aspects of the app are:

• The instructions panel (left of the page)
• The code editor (right of the page)
• The navigation controls (”Complete and continue” button, lesson selector, etc)

In a moment, we’ll take a look at each aspect individually. But first, let’s first talk about the tutorial content.

Tutorial content

My interactive tutorial is on building a cat image generator using CATAAS (Cat-as-a-Service) and Vue 3.

To write the content, I took an approach similar to writing a normal blog post tutorial — I wrote a recipe-like series of steps that tell the developer what to do and the changes to the code they’ll need to make.

The main differences between a blog tutorial and an interactive tutorial are:

• Each step of the tutorial will be in a different file e.g. step1.md, step2.md, etc.
• Rather than providing snippets of code for examples, you need to capture the state of the whole codebase for each step.

Instructions panel

On the left of the app is the instruction panel where the developer can read what they’re meant to do to complete each step of the tutorial.

To create this, I made a series of markdown files — one for each step. These are loaded dynamically and rendered as HTML using the markdown-it markdown library.

Here’s some pseudo-code to give you a sense of how it works:

content/step1/instructions.md

Welcome to this *interactive* tutorial where you'll learn stuff.

app.js

async function loadStep(num) {
  const res = await fetch(`/content/step${num}/instructions.md`)
  const markdown = await res.text()
  const html = md.render(markdown)
  // render html into your page
}
loadStep(1)

Code editor

The centerpiece of the app is the in-browser code editor. Here the developer can write code and have it be compiled and displayed directly in the browser. I used Stackblitz for this, but Code Sandbox is another option.

I’ll again supply some pseudo-code to explain how it works.

First, create a mount element on the page and give it an id attribute e.g. editor.

index.html

<div id="editor"></div>

Next, embed Stackblitz on the page using the JavaScript SDK. In the options object, you can provide the initial code state, NPM dependencies to be loaded into the environment, and so on.

app.js

import sdk from '@stackblitz/sdk'
const opts = {
  // specify the initial code state, dependencies to load etc.
}
const vm = sdk.embedProject('#editor', opts)

We saw above that you could use a function loadStep to load your instructions markdown file for the editor.

You can extend this function to load the code state of each step as well. The Stackblitz editor provides the applyDiff API method for this.

app.js

async function loadStep(num) {
  ...
  const files = {
    'index.html': await fetch(`/content/step${num}/index.html`)
  }
  await vm.applyFsDiff(files)
}

Navigation

The last essential piece of the app concerns “navigation” i.e. how the user can progress themselves through the tutorial steps. For this, I provided a “Next step” button as well as a list of step links.

This pseudo-code is a React component showing how you might create a “Next step” button. It includes a click handling method which will be responsible for incrementing the current step and then loading the corresponding instructions and code editor files.

src/components/NextStep.jsx

class StepNav extends React.Component {
  async loadStep(num) {
    // load instructions and code files
  }
  handleClick() {
    const stepNum = this.state.stepNum++
    this.setState({ stepNum })
    await loadStep(stepNum)
  }
  render() {
    return (
      ...
      <button onClick={this.handleClick}>Next step</button>
    )
  }
}

Wrap up

Interactive tutorials are a great way to get developers up and running with your product quickly and are an exciting alternative to blog-based tutorials.

By adding one or more interactive tutorials to your developer docs you can allow developers to try your product without the hassle of installing anything locally.

Here I’ve only given a very high-level overview of how you can create your own. If you need assistance or advice, feel free to get in touch with me through my website.