Lorna Jane Mitchell - Beyond the API Reference: Developer Experience for APIs

API the Docs Virtual Event Series 2020 Recap

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

View Beyond the API Reference on Notist.



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.

Code Samples

Use copy-and-paste examples to get developers to start using your product quickly. The more examples you have the better.

HowTo Guides

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.

Troubleshooting Guide

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!

Demo Apps

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

SDKs

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.