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

MENUTools Platter | 10€

A main course to satisfy all
appetites by providing
ready-to-run libraries

Perfect for sharing! A variety
of in-season tools to improveand enhance the developer
experience

Request/Response Examples | 7€

Troubleshooting Guide | 8€

SDKs and Libraries | 12€

Tasty requests and responses,served with a side of sample data

Sample a selection of delectable
solutions to common problemsand 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 adigital 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 thecode 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 commonproblems, 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, servedwith 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