Want People to Use Your API Documentation? 5 Expert Tips
Creating API documentation is a labor of love. It takes a great deal of time to capture all the information needed to consume an API, therefore API documentation has to be clear and easy-to-use, or developers won’t use it. If they don’t use your API documentation, you’re in for a ton of one-off questions, errors, and eventual abandonment of your API.
At Stoplight, we believe that documentation should be battle tested to ensure you don’t spend time worrying about your docs. To that end, I’ve compiled 5 tips and tricks to help make your documentation more reliable, accessible, and comprehensive.
1. Write API documentation that humans (not machines) can read
In many cases, API documentation seems to be written for a machine rather than a human. Remember that developers will read your API documentation in order to connect with your API. Don’t use over complex sentences and words. Instead, use simple language so readers will stay interested throughout your point.
2. Power your API documentation using your API spec
Documentation often gets out of sync with the latest versions of an API. APIs are constantly changing which means your API Documentation must be updated too. This can cause a disconnect if you have separate teams that manage the design and the documentation. To solve this, you can power your documentation using your API specification. By connecting the two, you can automatically generate human readable documentation for all of your API’s inputs and outputs. This finally allows you to confidently make changes to your spec and know your documentation will be automatically updated without any extra effort or collaboration.
3. Know the varying needs of API documentation consumers
There are roughly 3 types of interactions consumers will make with API documentation:
- Evaluating if the API fits their use case
- Learning the API in order to integrate with it
- Diagnosing an issue with an integration or consumer
Your documentation must address the needs of all these prospective documentation consumers. Explaining all the inputs, outputs, limitations, and known issues in detail will help both the person evaluating the API and the one integrating against it. Making documentation searchable with easy navigation will help new and experienced users move quickly between the documentation and their integration.
4. Use API Documentation tools for the best editing and design experience
Many API documentation tools will format docs to have a familiar look while also complying with industry standards. Code samples will be some of the most valuable pieces of information in your docs. Include all major coding languages to tailor your examples to the broadest range of developers. Take it one step further by including an HTTP request maker for each of your endpoints. This allows consumers to quickly try out your API with pre-built requests without having to write any code.
5. Start simple and add more detail over time
Documenting all the ways to use your API can be pretty overwhelming. It’s important to start with the major use cases with the expectation that you’ll be adding more as you go on. Before you start, make a list of critical inputs that consumers will need. This will likely include an article about authentication such as how to acquire and use an API key. Publish your API documentation with as much detail as you can at launch. Remember that as your API grows, so should your documentation.
P.S. We also wrote a Technical Writers Playbook for the Stoplight Platform that you can check out here.
