This talk was presented at API The Docs Virtual 2020 event series on 4 November. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!
Visit the API The Docs 2020 recaps overview to explore all presentations this year.
The highest level obstacle to consuming APIs is the lack of documentation [*].
Respondents with 6+ years of API development experience were more likely to mention lack of documentation than those with 0–5 years of experience.
If your API doesn’t have a really good documentation, it’s not an API. If no one can use it, don’t publish it in the first place.
In general, people don’t order the whole menu at once, they discover the selection in a series of different visits. They choose enough to satisfy their needs. What you have to do is to direct the resources you have to make the best impact you can.
Every API is someone’s first API. So don’t be afraid to over-explain things.
Utilize the capabilities of the OpenAPI specification format, give as much context, and as many details as you can.
Examples of requests and responses can fill a gap for all sorts of use-cases.
Use copy-and-paste examples to get developers to start using your product quickly. The more examples you have the better.
How to [...] X with Y, where X is a common task or goal, like sending an SMS, or taking a photo; and Y is a tech stack that you can use to solve that task or reach the goal. These guides can be individual sections, articles, blog posts even.
aka FAQ, or sometimes Tips & Tricks
If there are tools that work well with your products, like for local development, for API calls, for mock API servers, etc., share them!
Use working but minimal versions of likely applications:
Only ship what you can support! Don’t be afraid to do a quite limited installable package. And just like with your APIs, documentation is key.