Five Elements of Good API Documentation
API documentation is much more than just a reference
Writing good API documentation can be harder than building the API itself. Many people don't think this way and don't invest in learning how to write the best documentation for their API. Instead, they simply generate a reference from their OpenAPI—or equivalent—definition and then hope everyone will be able to understand everything.
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.
Well, most people you talk to tell you they feel lost whenever they're browsing an API reference. Helping those people find their way into your API is crucial, otherwise, you'll lose them right when they're just getting started. Let's look at the five elements that any good API documentation should have.
Customized "getting started" how-to
The first element of good documentation is the one that potential users will see when they first find your API. After they find your API documentation, those users want to know, as quickly as possible, how they can start interacting with what you're offering. Imagine you're one of those people. The only thing they know is what benefits your API can offer them. How can you help them onboard and obtain those benefits?
One way to offer a good first experience to new users is to think about them in cohorts, or personas. Then, you can present your API to each cohort in a customized, almost personalized way. Software developers don't have the same needs as product managers do, for example. When you align your welcome message to each of the cohorts, you're able to give them the information they need to get started.
The how-to should be a sequence of actions that readers can easily follow to onboard your API. You don't need to explain how your API works, or what its benefits are. You simply need to guide people into starting to use your API. An interesting way to do this is to provide a Web-based console that anyone can use to interact with the API. Another approach is to ask readers how they want to integrate with your API and provide them with the right SDKs and code snippets along with the how-to.
Use-case Tutorials
After helping users get started by offering them step-by-step instructions, you can show them how different parts of your API work with the help of tutorials. However, tutorials are only as good as the topic they're focused on. A good approach is to identify the most important use cases from your audience and translate them into tutorials. Users will then be able to go through each tutorial to learn how your API aligns with the use cases they're interested in.
Each tutorial you write should describe its objectives to readers and provide them with enough context to understand its importance. Additionally, it should clearly list any prerequisites and requirements that users need to meet. Examples of prerequisites include having signed up to your API, having a certain software installed, and having knowledge of a particular programming language. The tutorial should then be a list of step-by-step instructions that are easy to follow and understand.
Finally, each tutorial should have clear information about its version, the version of your API it refers to, and the date and time when it was last updated. This information is essential, so readers can understand if the tutorial is up-to-date with your API. At the end of the tutorial, give readers follow-up options they can use to learn more. Also, give them an option to share their feedback about the tutorial.
Full API reference
The API reference is, traditionally, what every API producer has been offering as documentation. Having a full reference is critical because it's the comprehensive source of truth of your API. It should have information about all the operations your API offers, their inputs, outputs, possible error messages, and any particular details important to users.
Depending on the type of API you're building, having a reference can be simple. As long as you maintain a machine-readable API definition, you can easily convert it into a user-friendly browsable reference. By making sure the API definition is always up-to-date and, whenever you make any change, you can automatically update the reference.
Code samples
To make it easy for readers, provide meaningful code samples and examples to illustrate each step of tutorials and each referenced API operation. Share enough explanation of what each code sample does, so users can fully understand it. Even better, provide each code sample in the programming language of choice of the reader.
Examples of items that deserve code samples include showing how a user can do authentication, handling errors gracefully, performing asynchronous requests (if your API offers asynchronous features), handling scenarios where rate-limiting is applied, and handling Webhook requests (if Webhooks is something your API offers).
Along with each code sample, you can also share the result of its successful execution, so readers know what to expect when they try running the code themselves. Moreover, if you want to increase readers' trust, you can share any common issues with each code sample and provide troubleshooting instructions.
Changelog
An API changelog is a way to share any changes you introduce to any of the elements I mention above. The value of a changelog is in the level of detail of the changes you share. However, consistency and clarity are key when you want to keep users informed. Your goal is to make it easy for them to understand the impact each change has on the way they consume your API. Regularly updating the changelog is fundamental to reflect the latest changes accurately.
Things that should be on your API changelog include any features you added since the last time you reported changes, any deprecated or removed functionality, any bug or security fixes, and generic documentation updates. Each change should also include the impact it might create. Is the change something new you added that won't affect anyone negatively, or is it something you removed that you consider can break existing integrations?
Summary
By now, the value of good API documentation should be clear. Without good documentation, users find it hard to interact with your API and even to start using it, to begin with. There are many ways to go about when it comes to creating good API documentation. The five elements you just read about will increase the quality of your API by reducing the friction users have when interacting with it.
A combination of customized "getting started" how-tos with a set of tutorials written to align to specific use cases is an excellent starting point. If you add to these a full API reference, code samples, and an up-to-date changelog, then you have a winning combination.