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.
Lorna Jane Mitchell
Developer Advocate at Vonage
Lorna Jane's presentation(video recording)
Lorna Jane's slides
API the Docs Podcast
The Evolution of a Documentation Platform - Interview with Fabian Rodriguez (Vonage)
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.
API Experience menu
- Getting Started Docs
- Authentication Overview
- Common Tasks
- SDKs and Libraries
- Request/Response Example
- Human Contact
- Tools Platter
- Troubleshooting Guide
- Extras like video content, code snippets, and demo apps
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.
Getting Started Content
- Overview content that introduces developers to the landscape: architectural style, authentication method, response format, etc.
- Include working examples that developers can copy-paste and try out.
- Add links to any resources and dependencies that developers need to know and have to start using your API.
Every API is someone’s first API. So don’t be afraid to over-explain things.
Include example responses in the API reference
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
- A dedicated place for common solutions to common problems: ask support people or check developer forums
- Don’t have to be finished immediately - it’s a living document
Recommended Related Tools
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:
- Plausible but not super-complex
- Pick your favourite use-cases
- Take inspiration from your Sales’ “verticals”
- Mix up technologies to appeal to different communities
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.
Be Real, Be Visible
- Don’t hide behind your company, or a brand, or a team: you don’t have to be available all the time
- Use your name
- Direct people where they can find you: be part of the conversation
[*] based on the article called 2020 State of the API report published by Postman.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.