The API landscape is growing quickly. Organizations are more reliant on connected web services and integrations than ever before, and providers have the opportunity to grow the adoption of their APIs dramatically.
Developers want to work with APIs that are easy-to-learn and perform as expected. High-quaility documentation can set expectations, educate your users, and attract developers to start new projects with your service.
Here are some ways for your team to design best-in-class documentation:
1. Tell a Big Story
When someone first shows up to view your API documentation, what are they greeted with?
If you are trying to drive adoption and build a base of regular users, you should tell a story. Documentation can have a bad rap because it’s typically technical and exhaustive, but for many companies, documentation is now both the packaging and instruction manual for their product.
What is your story, and what role do consumers of your API play in that story? For example, Marvel has a public API that lets developers query the comic book canon.
Marvel API documentation: https://developer.marvel.com/docs
When someone arrives to the portal, the story is crystal clear: “Create Awesome Stuff with the World’s Greatest Comic API”.
Your organization’s APIs might not rely on superpowers, but there’s probably a story out there that speaks to your strengths and gets developers excited to be working with your API.
2. Provide a Clear Starting Point
Alright, so you’ve rallied your new users with a compelling story. Now what?
Provide a clear starting point so that developers know where to go first to get acquainted with your API. The API documentation for Slack, the popular messaging tool, does a good job with this. They tell a story with a dynamic heading, “Build: brilliant bots”, and introduce their side-panel navigation with a “Start here” section.
Slack API Documentation: https://api.slack.com/
Before someone even scrolls down, they have a clear place to start learning about the API, which also gives Slack a dedicated place to set expectations for new users. The “Start here” section is aligned with the standard software development lifecycle, going from planning, to designing, to building. Consider what structure makes the most sense for your API, but make sure you are providing new users with direction when they come to your documentation for the first time.
3. Create a Structure that Facilitates Common Use Cases
Unless a developer is purely browsing, they probably already have a project in mind by the time they reach your documentation. By calling out the most common use cases or actions your API can support, you can reduce the time it takes for developers to find the information that they need. Slack also does a great job with this, calling out actions like “Send messages”, “Create simple workflows”, and “Build bots” on the homepage.
Take time to consider what types of things your end-users are trying to build and how you can provide them will all the most helpful information up front. If you can make their first project with your API easy, you increase the likelihood that they’ll be back regularly.
4. Write for Humans First
Some developers might never interact with your organization beyond your documentation. If your documentation is all clinical and dry, developers might find what they need but the experience won’t stand out. Think about the tone of your documentation. Is it conversational?
If the developer were sitting next to you, how would you explain the authentication options?
You need to be trustworthy so don’t lean too heavily into slang or go overboard, but don’t be boring and cryptic either. To get started, you might want to run your existing documentation through a readability calculator.
These calculators will keep you honest and highlight sections where you might have run-on sentences or too many long words. Coding is hard enough; reading should be easy.
5. Make it Comprehensive
Developers expect a lot out of a provider’s API documentation. In our 2019 State of API report, we asked respondents to select the “top 5 most important things you look for in API documentation”. Here are the results from over 3,000 software professionals:
Make sure that you are exhaustive in the resources you provide to consumers. Imagine the most-engaged user who could come to your documentation, and don’t let a lack of documentation hold them back.
That doesn’t mean flood users with all the information possible. Employ hierarchy in your documentation so that light users can quickly engage with common use cases and power users can click through the details to their heart’s content.
6. Make it Interactive
In the chart above, respondents selected “Examples” as the most important component of API documentation. Developers want to get hands-on as soon as possible to see what could be possible with your API.
With interactive documentation, developers can quickly test out different API calls. The Marvel portal we referenced earlier has this option. When you create an account, you are automatically provided with an API key. You can use that key to make calls against all the different end points and test out different operations. This interactive page also helps familiarize developers with the parameters and error messages they should expect to see.
Marvel's Interactive Documentation: https://developer.marvel.com/docs
7. Standardize Your API Design with the OpenAPI Specification
The OpenAPI Specification (formerly known as the Swagger Specification) is an API description format for REST APIs, which has quickly become the industry standard. In our 2019 State of API survey, we found that nearly 70% of respondents are currently using the Swagger/OpenAPI standards for defining their APIs.
This format is designed to be easy to learn and readable to both humans and machines.
By structuring your APIs in a consistent way, your organization is able to provide developers with a consistent experience. They’ll know what to expect and where to find it.
Organizations that adopt the OpenAPI specification can leverage open source tools like SwaggerUI to automatically turn their API definitions into interactive documentation.
You can see how documentation with SwaggerUI works by visting the Swagger Petstore: https://petstore.swagger.io/
SwaggerUI, as well as all of the other open source Swagger tools, are available in one central platform called SwaggerHub. If your team is looking to standardize around the OpenAPI Specification, you can create a free account and start importing your APIs right away.
8. Highlight Tutorials, FAQs, and Case Studies
Your documentation is a learning platform for your API.
You can explain how to use your API, but showing how to use your API can really bring it to life. Create tutorials for simple project-types and then link to them in your documentation. This example below from Slack shows the types of articles and tutorials they are building and promoting to help educate users on their API.
Slack API Tutorials: https://api.slack.com/tutorials
They also list a few case studies. To really drive adoption of your API, you should not only educate visitors, but also provide them with inspiration for new projects.
One creative example that Slack cites is Kip, a penguin-themed bot that helps coordinate food orders for offices. Make it easy for developers to see what is possible with your API by highlighting some of your most creative users.
9. Encourage Feedback from Users
How effective is your documentation?
You could look at different metrics as proxies, such as page views, consumers, or number of calls, but with those metrics alone, your team is left to make a number of assumptions.
You could survey users and see what they think, but it can be tough to stay disciplined about requesting user feedback if it isn’t built into your process or infrastructure. The best documentation encourages feedback from users, within the documentation.
Stripe, the popular payment vendor, does a great job with this by asking “Was this section helpful?” at the end of each section within their documentation. It takes very little time for users to click “Yes” or “No” as they are going through.
By asking this question, they can clearly see what sections are being marked most unhelpful, which sections have the most engaged visitors, and then prioritize improvements accordingly.
Stripe API Documentation: https://stripe.com/docs/api
This element provides you with a quantitative measure for your existing documentation, but you still won’t know what might be missing. By combining embedded quantitative measures with qualitative surveys, you can get a pretty good sense of the state of your documentation.
10. Keep it Up to Date
It’s really frustrating to read documentation that only makes things more confusing.
If your documentation isn’t up to date, it can reflect poorly on your organization and discourage developers from engaging with your API.
In our 2019 State of API report, we asked respondents, “What are the biggest obstacles to providing up-to-date API documentation?” The top 3 responses were:
- Lacking time and/or resources due to workload
- Increasing demands for speed of delivery
- Lacking tools or technologies
To tackle these challenges, your team has to rely on tools that can speed up your processes and give you back time. We already mentioned how tools like SwaggerUI and the SwaggerHub platform can automatically generate documentation for your API definitions.
Beyond that, look for dependencies that slow down your team. Does your documentation team have to wait on development work to finish up before getting started?
Waiting on other teams for work creates avoidable time crunches and subsequently impairs the quality of your documentation.
If your team is using the OpenAPI specification, tools like ServiceV Pro and VirtServer make it easy to convert your API design into a virtual service that can be shared across teams.
Your documentation, development, and testing teams can all work in parallel using the virtual service. With one shared source-of-truth for the project, you can start accurately documenting expected responses without waiting on other teams.
If your team is using SwaggerHub, there’s a simple integration with ServiceV to make virtualization a natural part of your workflow.
Learn More About API Documentation:
Want to read more about documentation best practices? These are some of our favorite articles on the subject, many of which helped inform this piece. Go check them out!
Read more: