Ask 10 developers a question and you’ll usually get 10 different answers. However, one place many developers agree is the most annoying part of using a new API or dev tool: dealing with its documentation, which is often outdated and inaccurate. The best API documentation reaches beyond simple accuracy. Good API documentation makes it easy for developers to use, reference, and explore.
Review these 8 examples of great API documentation and emulate them with your own docs. To make the easier, we’ve focused on one primary lesson for each:
- Plaid shows developers what’s possible
- GitHub gets started quickly
- Twilio shares use cases
- APIMatic provides language-specific content
- Stripe makes it copy-paste easy
- SendGrid generates API references
- Dropbox lets developers interact with its API
- Auth0 shares lessons on its developer blog
While nobody makes bad documentation on purpose, everybody can help make it better. This post will cover these common areas of documentation, plus some areas you might not typically see called docs. Based on a great examples of each, you can implement some of these ideas today.
Show Developers What’s Possible
A developer wants to quickly answer whether your solution will solve their problem. Make it easy to find your portal or developer home page. Then, ensure you clearly communicate the main benefits of your API or platform.
Plaid could have easily written something hand-wavy on its home page like “the future of financial services.” In fact, that line shows up further down the page, but in the context of five common use cases. In one sentence, developers know they can use Plaid to connect to their users’ bank accounts.
Keep in mind that this is the homepage for the whole company. Since the API is core to everything the company does, you can also find docs in the global navigation. On the developer home page you can quickly see more about what’s possible: transactions, income, balance, and more is available with Plaid. Between these two pages, developers can figure out in a hurry (and without even signing up) whether they’ll be able to solve their problem with Plaid.
Get Started Quickly
The most important API documentation you can provide is a quickstart or getting started guide. This meets a developer at a basic level of knowledge and holds their hand to a quick win. You’ve already told them what’s possible, so here you need to show them.
GitHub’s REST v3 API guide remains a great example of taking a potentially complicated topic and layering complexity one step at a time. It starts with unauthenticated calls, including one that returns a repository, a common object for the GitHub API. Once the dev has initial success, the guide adds authentication, showing an example call to your own profile. There’s a lot more that happens on GitHub, but developers have the tools to dig deeper after completing this tutorial.
Once you have a getting started guide, make sure you make it easy for developers to find. Include it as a primary call to action on your documentation home page and send it in any sequence of welcome emails when developers sign up.
Share Use Cases
There are probably many ways a developer can put your tool to work. Don’t make them flex their creativity muscles. Instead, share top use cases. Paradoxically, these examples help developers become more creative once you’ve seeded their imagination in the right direction.
Twilio has always done a great job of inspiring with use cases. The latest iteration uses a more enterprise term, solutions, but the details show their developer roots.
The company backs up these use cases with solid documentation that would fit well in other sections of this post. In particular, Twilio has use case tutorials that take on some of these solutions with its APIs from a developer point of view.
Provide Language-specific Content
Any modern programming language should be able to make HTTP requests. But there’s no quicker way to get up to speed than providing an SDK in the developer’s preferred language. By installing with a package manager or downloading the library, a developer can skip preparing the API calls with appropriate headers and other details. Best of all, SDKs typically simplify authentication, often the hardest part of getting started with an API.
You’ll find many big players taking the language-specific approach. APIMatic (where I’m an advisor) offers a product that generates SDKs and examples across about a dozen languages and frameworks. The technology is enabled by OpenAPI and other API descriptions (see generating API references below).
Make it Copy-Paste Easy
One of the most important jobs of documentation is to get developers started quickly. Providing code or even a curl command that they can copy and paste is the quickest way to show the value of an API.
Stripe’s documentation is often pointed to as the best, likely because of its copy-paste reference. You can explore what is possible and grab the exact code necessary to perform the operation–complete with a working API token (your own if you are logged in!).
Recently, Stripe has taken this copy-paste concept farther with its new tutorial format. These guides use complete sample apps alongside approachable descriptions—and provide a one-click copy of the relevant code for each step.
Generate API References
There are many kinds of documentation, but the foundation is an up-to-date reference. This document shows everything that is possible in black-and-white, just-the-facts format. Sure, the layout and colors might differ, but a reference is the source of truth.
Increasingly, API references are built from OpenAPI documents or other API descriptions. The OpenAPI Initiative has created an industry-driven format to define an API’s elements. These JSON or YAML documents are intended to be machine-readable and can be used many ways. For documentation, you can use OpenAPI to generate references. Whenever any API is updated, those changes should automatically be available in an updated reference.
SendGrid’s API reference (above) has a machine-readable version in a GitHub repo. The email company uses EveryDeveloper client Stoplight hosted documentation to generate the docs whenever the API changes.
Let Developers Interact With Your API
It’s one thing to see what’s possible in a reference–it’s even better to experience it. Create an API explorer or include the functionality in your API reference.
The Dropbox API Explorer helps you quickly see the data behind API calls. Even better, it has a point-and-click token generator to let you see your own data in the responses.
Share Lessons on Your Blog
The final item on this list is a bit of an outlier, but is an important one if you want to reach developers. Your blog is not documentation itself, but plays an important role in educating and inspiring your audience. If developers are your customers, your blog posts should speak their language.
And not just speak their programming language. You want to share best practices for your specific technical area. Explore specific use cases beyond merely how it’s accomplished, but why you’d build your way. Technical blog posts are a key piece of developer marketing that works.
While the Auth0 blog (above) has some self-promotion above the fold, the latest posts keep the focus on solving developer problems. You’ll find great technical tutorials, deep dives into common issues the audience faces, and plenty of Auth0 engineering tips to show that it’s a developer-centric company.
Upgrade Your Developer Experience
Perform an audit of your existing developer portal and content, making a list of potential areas for attention. Perhaps you have a getting started guide, but it needs some updates to be simpler or focus on a different area of your developer product. Maybe you have a list of use cases already in mind that you can share to stoke your audience’s imagination. Or, think about some new articles on your blog if you haven’t published anything in a few months… or maybe even a year.
Take one or two of these areas on to improve your documentation today. It doesn’t have to be a lot of work. With consistent attention, you’ll have better docs and happier developers.