A presentation at ApitheDocs Virtual Season 2 by Lorna Jane Mitchell
Beyond the API Reference Lorna Mitchell, Vonage
In Praise of API Documentation @lornajane
Improving API Documentation @lornajane
Getting Started Docs | 4€ An ideal vanilla opener, introducing a twist of freshness Authentication Overview | 8€ Smooth notes in this starter to get users up and running easily MENU SDKs and Libraries | 12€ A main course to satisfy all appetites by providing ready-to-run libraries Request/Response Examples | 7€ Tasty requests and responses, served with a side of sample data Tools Platter | 10€ Perfect for sharing! A variety of in-season tools to improve and enhance the developer experience Troubleshooting Guide | 8€ Sample a selection of delectable solutions to common problems and gotchas Common Tasks | 5€ A fusion of tastes bringing together non-trivial use cases. Served with your choice of: - Java - Node.js - PHP Human Contact | 4€ Extras | 2€ We specialise in service with a digital smile! Find us online. Add a little something more: - video content - code snippets - demo apps
Getting Started Content Developers do read documentation (sometimes) • Overview content: introduce developers to the landscape • Include (at least) one working example • Link to any dependencies • sign up page • pricing information @lornajane
Examples are Worth Many Words Include example responses in the API reference. @lornajane
Code Samples Are Awesome Copy-and-paste examples to get developers started quickly. @lornajane
Code Sample Mechanics 1. Create a repository full of working standalone examples 2. In your documentation, write words and then refer to the code by repo/file/line number 3. Repeat for as many languages as you wish, plus curl @lornajane
HowTo: X with Y X is a common task; Y is a tech stack @lornajane
Troubleshooting Guide Create a dedicated space for common solutions to common problems, and consider it a living document • Does a common error indicate a missing dependency? • A generic message have a non-obvious remedy? • A great tool help with a common gotcha? Share the knowledge! @lornajane
Recommend Related Tools Are there tools that work well with your products? Share them! For example we have: • Ngrok for local development with webhooks • Postman (of course!) for API calls • Prism for a mock API server for testing • Sample apps to help debugging events @lornajane
Demo Apps Working but minimal versions of likely applications • Pick your favourite use cases • Take inspiration from Sales’ “verticals” • Mix up technologies to appeal to different communities @lornajane
SDKs (OK, this is a whole other talk, I know) @lornajane
Be Real Don’t hide behind the team or company. • Use your name (or handle) • Direct people to where they can find you/help @lornajane
Chef’s Recommendations Request/Response Examples | 7€ Tasty requests and responses, served with a side of sample data Getting Started Docs | 4€ An ideal vanilla opener, introducing a twist of freshness Common Tasks | 5€ A fusion of tastes bringing together non-trivial use cases. Served with your choice of: - Java - Node.js - PHP
Resources • State of API Report: https://www.postman.com/state-of-api • Vonage SDKs: https://developer.nexmo.com/tools • Vonage Blog: https://nexmo.com/blog • Consistent and Delightful SDKs: https://nordicapis.com/ • These slides: https://noti.st/lornajane/SEO0Bm • My blog and more: https://lornajane.net @lornajane
An API without any documentation is no API at all, but too many stop at the API reference. This session goes beyond that vital ingredient of Developer Experience and looks at what else can go into a successful recipe. We’ll dive into tutorials, code samples, integrations, and other ways that can enable users to get going or to level up with your API. This session is recommended for anyone who wants to improve the experience of users of their API.
