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 9 great examples of 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
- Render 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
- LogRocket shares lessons on its developer blog
- Gremlin keeps engineers learning
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 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 homepage. Then, ensure you clearly communicate the main benefits of your API or platform.
Plaid could have easily written something hand-wavy on its homepage 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 homepage, 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.
Render’s developer homepage gets right to the point with quickstarts for every language and framework it supports. Each is backed by a GitHub repo and clear instructions for how to deploy it on Render’s cloud hosting platform.
Find the quick win or “hello world” for your developer product, then create a short tutorial to support this basic use case. For Render, the win is a deployed repo. For you, it might be a single API call or a code snippet that can be controlled from your dashboard. This first example won’t be deployed to production but helps show what’s possible. Next, you can show how your product is used in “real-life” situations.
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 is attempting to hit a wide audience with its current messaging, but its developer roots remain. Twilio has always done a great job of inspiring with use cases, something all audiences appreciate. The latest iteration (shown above) uses a more enterprise term, solutions, but eases naturally from high-level discussion to code-packed tutorials.
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 within its docs, so these solutions can be discovered and described 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 generate 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, with its beautiful design and multi-column layout. Though many have copied how Stripe docs look, few have gone as far as the payments company to make its reference copy-paste friendly. From the earliest days of Stripe, every API call can be copied and pasted directly, without any intervening edits—and that includes a working API key.
You can explore what is possible in the Stripe reference and grab the exact code necessary to perform the operation. If you’re logged in, it will even include your own token (rather than the public version).
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 in 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 of its OpenAPI document in a GitHub repo. When changes to the API are published into the OpenAPI document, SendGrid automatically runs scripts to generate correct user-facing reference documentation for its API. Many companies use an OpenAPI tool like Stoplight (an EveryDeveloper client) to maintain a source of truth from which to generate API references.
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
Compared to other items on this list, this one is a bit of an outlier. If you want to reach more of the right developers, you need to attract them with technical content that solves a problem. 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.
LogRocket is a front-end monitoring tool. It helps development and product teams monitor performance, usability, and errors. However, its blog topics are much more expansive. The company publishes multiple posts per week with general front-end education. Its content is not focused on its product, but rather the problems its ideal developer customer experiences.
LogRocket treats its blog like a publication that developers would read even when they aren’t shopping for monitoring. That way, when they do have a problem that LogRocket solves, they’ll remember who taught them important front-end lessons.
Keep Engineers Learning
Blog content, usually 1,000-2,000 words, can offer targeted lessons to developer readers. Yet, the problems that technical products solve are often much bigger than can be covered with your typical blog fare. This is where deep, educational guides can take over. Rather than sitting within your documentation (there are other options for that type of content), these guides help explain problems—and solutions—without leveraging a specific product.
Gremlin’s Chaos Monkey Guide may be the best example of this type of content. At over 18,000 words, it’s treated like an entire section of Gremlin’s site. The guide itself is split into multiple pages and each covers one area of Chaos Engineering. Gremlin’s product helps teams implement the chaos monkey pattern, but this guide *does not* dig into its implementation.
This guide ranks well for relevant, high-volume topics, so it likely brings evergreen traffic. In addition, Gremlin links to the guide in blog posts, onboarding emails, and in prominent navigation. You wouldn’t want to dilute the power of this format with too many, so start with one strategic guide of high potential. Then, focus your efforts to make it successful.
See more examples of these guides (which we call Signature content).
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—a documentation team can help you make the most impactful changes quickly. With consistent attention, you’ll have better docs and happier developers.
If you still aren’t sure where to start, assess the current state of your developer experience with our free DX Quiz.