Why API Tutorials Matter
Why should you offer an API tutorial if most developers are just looking for quick answers?
According to the Diataxis framework, the purpose of a tutorial "is not to help the user get something done, but to help them learn." In other words, tutorials are lessons that help readers learn about the topic being presented. So, if tutorials don't give API consumers the information they need to complete their tasks, what is their value?
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
You could argue that most API consumers consult documentation only when they can't get their jobs done. Sometimes the help they need is related to onboarding, other times they're just looking for a quick answer to a persistent question. The reality is that most people don't bother to read documentation, especially if it doesn't provide anything immediately useful. Like a how-to would.
You can see how-tos as recipes that guide readers into getting something concrete done. However, the same doesn't happen with tutorials. Instead, a tutorial is a lesson where the reader follows a set of steps to learn something—in this case your API. A tutorial is something consumers read when they're experimenting with your API. The experimentation helps consumers understand if your API is what they need and a tutorial is one way to show them what's possible and what's not.
The best tutorials present information that helps consumers fulfill a use-case scenario that feels real and meaningful. Instead of coming up with a made-up use-case, you can research what are the things your API consumers would want to do. Then, create tutorials that teach how to achieve those results with your API. The goal of the tutorial is to educate readers on how they can use your API—or some of its operations—to get their job done.
So, what are the elements that a good API tutorial should have? Let's look at some of the most important ones:
A safe environment to learn and practice: Readers should be able to follow the tutorial in a non-destructive way. To make that happen, you should provide a sandbox or a way to let consumers interact with your API on non-production data.
A list of prerequisites: Participants should know what are the things they need to know or do to successfully complete the tutorial. The list can include specific knowledge of a programming language, having access to API credentials, and being able to deploy code. What's important is that readers have all the tools and knowledge they need to go through the tutorial before they begin.
Choice of technology: Letting participants pick the tools and technologies they want to use during the tutorial makes the learning more enjoyable. Consumers will feel what it's like to access your API using the technologies they're accustomed to.
Easy access to the API reference: At any time during the tutorial, participants should have quick and easy access to the API reference. You can even present contextual links to the part of the reference that relates to the section of the tutorial being studied.
API access credentials: The tutorial would be meaningless if participants can't access the API. Provide API access credentials in a way that's easy for readers to use them. Preferably offer credentials to a sandbox or a test environment.
A clear goal: Explain right at the beginning of the tutorial what the goal is and how participants can measure their success. Throughout the tutorial give clues to how close readers are to achieving the proposed goal.
A thread to follow: Offer a concise sequence of items that lead to a successful conclusion. Keep participants interested with a growing difficulty throughout the tutorial associated with a growing knowledge.
Let's look at examples of interesting tutorials to see how these elements stack up. The first example comes from Stripe and teaches readers—in this case viewers, because it's a video tutorial—how to accept payments using their API. Even though they don't offer all the elements mentioned before, their video tutorials are easy to follow and learn from.
Another example is Algolia, the popular search service. Similarly to Stripe they also offer video tutorials. However, let's look now at the way they present their interactive tutorial, directly accessible from their documentation page.
I could go on and show other examples but I think you get the picture by now. There are elements common to these tutorials that make them easy to follow. By providing a thread to follow you guide participants into a successful outcome where they'll learn how to use your API.
Now that you've seen what a good tutorial looks like you can try to create your own. You should align your choice of how you present the tutorial with your audience. If you know your audience prefers video then you should invest in doing a video tutorial. Otherwise, you align with how participants will feel more engaged.
The tools you use depend on the format of the tutorial you want to create. In all cases you'll need a way to craft written content, ready-to-use code either in the form of snippets or full SDKs, a complete API reference, and a good lesson to teach your audience.
Summary
Even though most developers are looking for quick answers to fix their problems, they engage with tutorials as a way to dive deeply into your API. While tutorials aren't a way to solve immediate questions, they provide an ongoing learning opportunity so consumers can take the most out of what your API offers. That's why you should invest in offering good quality API tutorials in addition to all the other elements that any good API documentation should have.
alphadoc ( https://alphadoc.io/ ) is doing some cool work for building tutorials and a great DX for APIs.