Learn how to design a beautifully branded workspace with Stoplight Platform. Register for the interactive workshop here.
A comprehensive guide to API documentation best practices
Your API reference helps new developers see what’s possible. Later, they’ll return to remind themselves of syntax or specific functionality. In between, you’ll need documentation that helps them achieve common tasks with your API. These guides are less about describing functionality and more about defining use cases. Writing good API documentation guides & best practices helps developers understand why and how in addition to the what of a reference. You should keep these two areas in mind when writing API documentation to ensure they are fully useful and the best API docs possible.
Many developers will look for a tutorial before diving deep into your list of endpoints. The most important page of your documentation is the Getting Started guide. You can think of this as a Hello World that also takes them into an area of your API that shows them the benefits of integration. Often, your getting started guide will include your API’s most common use case.
Be careful not to attempt to cover too much in this initial guide, but enough that a developer can take the next steps on their own. To that end, you’ll want to include brief authentication instructions within this guide. If you use a complex authentication scheme like OAuth, consider providing personal tokens for developers, or supply a tool that easily goes through the OAuth flow. Every additional step is a rough edge that will keep developers from success. Your guides should help provide a smooth experience.
At the end of your getting started guide, what will a developer do next? Your answer to that question will help you figure out the next guides you need to write. Choose additional and advanced use cases, based around parts of your API.
Other potential guides might include how to use your API with popular frameworks, other APIs, or walking through entire applications. In fact, you can write API documentation and guides for every example app., which is the final type of documentation you’ll want to provide for developers.
A close relative of the guide is the example app, which includes all the code you need to produce a full integration with your API. Great API documentation will have at least one and often many examples, frequently with the source hosted in a public repository like GitHub.
The quickest way to add an example app to your documentation is to package all the code from your getting started guide. While the guide may take you through one section of code at a time, the example app should have everything you need in one place. It may only show basic usage of your API, but it offers a place to start with simple instructions that may look something like this:
While you may have a couple more steps, the ideal example app has the lowest possible barrier to getting something working.
You can inspire developers even more with example apps that support advanced use cases. You can provide a complete working app that someone might legitimately tweak and use, not just follow for learning. As with guides, understanding the problems that your developers are solving will help you determine what examples to share. You can also take inspiration from existing developers and share the use cases that are already popular.
We’ve already covered some great ways to approach various types of documentation. Now that you’re ready to take your API documentation to the next level, let’s look at some best practices for comprehensive, maintainable API docs.
Make it someone’s job. It doesn’t have to be their entire job, but it might be. The important thing is that you have someone watching out for how developers experience your documentation.
Involve multiple teams. Gather diverse perspectives to understand what’s needed in your documentation. You’ll find great insights from engineering, marketing, product, support, and more.
Look for type and topic coverage. Consider whether reference, guides, and examples are as complete as they should be. Are there areas of your API that aren’t covered well in one or more types of documentation? Use this to determine where to focus future efforts.
Include documentation in existing processes. As your API evolves, your documentation should keep up with the times. Automate where possible and make sure you consider whether new reference, guides, or examples should be included with new feature launches.
Acknowledge your documentation is a work in progress. It doesn’t need to be immediately perfect. Look for ways to incrementally improve one section or type at a time. Over time, alongside these other best practices, you’ll have great API documentation.
Whether you already have an OpenAPI description or need to create one, Stoplight is a powerful API documentation tool. Your API reference will always reflect your latest updates with beautiful, fully customizable themes. Interactive docs come out of the box, so you can show and tell developers how your API works.
Using Documentation Hubs, you can also includes guides and examples alongside your reference docs. Add pages and sub-pages to help developers better use your API. You’ll be able to easily include the three types of documentation covered in this guide.
See how Stoplight’s documentation can help you in creating and writing good comprehensive API documentation.