Beyond the API Reference

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