Good documentation is critical to an API’s success. Without it, implementation is slow, problems are hard to solve, and developers are frustrated. Every API provider should prioritize excellent documentation as a central piece of its developer experience strategy.
Why is everyone’s documentation so bad?
Developers find most API documentation tedious and unhelpful. In fact, according to our Hoss 2020 API Consumption Trends Report, poor documentation is the number one API complaint cited by developers.
Bad documentation often doesn’t include a guide to quickly getting started, is out of date, inaccurate, incomplete, inconsistent, and/or has poor navigation and a confusing user interface.
So, why is this happening? What are the all-too-common documentation pitfalls that API providers keep falling into?
Not making documentation a priority.Teams that aren’t given the time and resources to write great documentation or who focus solely on writing code won’t be able to compete in the increasingly crowded API space.
Not keeping documentation up to date. Documentation can become dated quickly. Too many teams either don’t update their documentation or update it manually (instead of automatically) after new releases.
Making assumptions about the audience. Never assume that developers are familiar with specific jargon – or even that your audience is 100% developers.
Overtaxing developers. Developing and writing are two very different skill sets. It’s a lot to ask of a developer to build a tool and to write about it in detail. Even if you have the skills, writing documentation is a lot of work – a lot of developers simply don’t want to do it.
The 10 ways to create delightful developer docs
Now you know what not to do when creating documentation for your API – but how can you delight developers who use your products?
1. Be comprehensive.
Developers reference your documentation and your website for a wide range of reasons - so don’t scatter the answers in different places. Your documentation should represent a convenient, one-stop shop for developers, whether they’re looking for tutorials, FAQs, helpful blog posts or links to external resources like YouTube videos and developer forums.
2. Start with the basics.
Believe it or not, very basic answers to questions like “what does this API do?” or “how can I start integrating this API?” are very often left unanswered in a company’s documentation.
Start at the very beginning – authentication details to start using your API, information about error standards, endpoints (how to consume them, how request and response works) – the basics. A huge and basic help to developers is to provide a changelog in your documentation that lists all of the recent updates to and versions of your API and how they might impact usage of your product.
3. Be clear and concise.
Don’t use jargon or be unnecessarily wordy. Keep documentation simple, clear and easy to read. Most developers’ goal is to understand an API or solve a problem as quickly as possible, so parsing through unnecessary prose is counterproductive. Remember that developers are human, too – and humans don’t like to read things that don’t make sense.
4. Be consistent and stay up to date.
Keep language in your documentation consistent and ensure that anyone who contributes to it or publishes an update adheres to a standard style. For example, decide whether you’re going to use the term “function” or “method” to describe a certain action – don’t switch between the two. Consistency can get lost as updates are made to documentation by different authors at different times, so it’s important to set this standard from the beginning to avoid confusion.
Which brings us to keeping documentation up to date. Staying current and correct is critical, as out of date and incorrect documentation is essentially useless to developers. But this requires a fair amount of maintenance. Make sure you have a plan in place for updating documentation after any new releases, updates or issues, and consider implementing automatic updates.
5. Provide a getting started guide.
This simple addition to your documentation is highly valued by developers and significantly reduces friction around using your product. Hoss’s favorite examples include Plaid and Vonage.
6. Include language-specific code snippets.
Writing code snippets for your users and including them in your documentation will save many, many hours of their time.
7. Make your documentation interactive.
Interactive documentation provides a space for developers to test their own examples before implementing them. One of Hoss’s favorite examples is the Dropbox API Explorer.
8. Provide tutorials.
Make it easy for developers to understand the possibilities of your API by providing simple tutorials for specific use cases. Vonage has a great use case tutorials section in its documentation.
9. Have a comments section.
Developers respond well to community and appreciate the opportunity to share and discuss problems, workarounds and questions. This can also take the form of a dedicated online community for your users, where you can surface frequently asked questions to make it simple for developers to find what they need quickly.
10. Prioritize good navigation and UI.
Make information easy to find and navigation intuitive. A prominent search function is a key component of great UI in API documentation as it makes finding the specific question a given developer might have infinitely faster.
“Sticky navigation,” where the navigation bar remains visible as the user scrolls, is another good practice for navigating documentation, because the pages can be quite long. Auth0 and Algolia are great examples of this practice. Another helpful tip is to incorporate a “saved scroll state,” which keeps a user’s place if a user refreshes the page. It also allows the user to share their specific place in a document by simply sharing the URL of the page.
Don’t disappoint, delight.
Creating great documentation can be a lot of work, but it’s important, and the payoff for your users is huge. If you make documentation a priority and follow the 10 steps above, you’ll be perfectly positioned to delight your customers.
Interested in reading more about developer experience?
Download the latest Hoss ebook: The New Era of Developer Experience: Delivering World-Class Support in a Competitive Landscape.
Top comments (0)