TADSummit Preview

Steven Goodwin: Engaging Developers

do-you-have-technical-documentation-for-your-apis-i-wont-read-them

The problem: Engaging Developers

People are not engaging with your product, and going elsewhere.

Maybe they try a couple of things, once, and then stop. Or they don’t continue their trial. Or they do something totally convoluted, using up unnecessary bandwidth, CPU cycles, or support tickets.

What can you do?

The cause:

There is no good on-boarding for new developers. We don’t need an encyclopedia of the API’s functionality, but rather a piecemeal approach to solving our problems – and quickly. Because if your API doesn’t let a dev get X, Y or Z working quickly then there’s another vendor out there just waiting to accommodate those developer dollars.

The solution:

Treat documentation like its own product.

  • Outline the vision
  • Create user stories
  • Build an MVP
  • Try before you buy
  • Staff it

Vision:

The interaction between your product, via its APIs, and the developer is a user interface.

Have you considered the expected experience of those developers, compared to your internal staff?

You are a telecoms company, but most of your customers won’t be.

Use web developer-friendly terminology. The web, by definition, is built on a small set of common protocols and APIs that a webdev expects third party APIs to be similarly structured. So having one style of API for SMS, and another for voice, is going to indicate a lack of vision on your part.

NOTE: Almost no one is doing microservices, let alone doing it well! So the idea that every customer is using 10 different languages with 100 different styles, and won’t be perturbed by 3 more within your singular product, is wrong. Adopt a singular vision.

User stories:

As a developer, I want to send an SMS. So provide a worked, end-to-end, example. This includes how the developer signs up to the site, gets tokens for the API, the endpoints, and library code for calling those endpoints. A single curl request is not enough.

TIP: each example should be fully stand-alone. Developers work on a copy-and-paste mentality so provide it in a single place.

MVP (Minimum Viable Product):

90% of the developers will use 10% of the features. (Just like product.) So focus on that 90% first. Start with a curl request, and then add a NodeJS example (for example.)

Then provide examples in other languages which your end users are likely to be using. (Ask customers and/or use analytics to determine which languages these are.)

Then build a solid library or module in that language to unify that request with the rest of your API functionality. Again, start with the obvious and most used sections, and later expand to provide complete functionality. If you have a web team, then incorporate the requests into your website so, when the user is logged in, they can make those same requests from the browser and note the network traffic from the debugger.

TIP: the Postman tool can export an HTTP request in many languages, use it for your first example.

TRIAL IT:

Developers are rarely buying a product, they’re buying a support service. So support them up front. Provide free credit for experiments. Have a sandbox to eliminate the fear of messing up. Provide links to forums, help chat, and so on. They’ll be testing your support channels as well as your API.

NOTE: Your business is not as important as you think! You are unlikely to get a million customers all trying to scam you for free SMS for life by cheating your APIs. We just don’t want credit to run out during a demo to our boss!

STAFF:

Documentation is not an afterthought for whichever developer is less busy on Friday afternoon. It is something that needs a lead (with vision), an architect (determining how to lead developers through), QA (to test each example) and so on. It is an ongoing job to make sure APIs and examples are up-to-date. It involves outreach to check message boards and forums. Or to post comments on blogs thanking users, or pointing out improvements or changes in later versions of the API. A developer relations team (devrels) need not be big, but it will be important.

TIP: Just because a developer has a word processor, doesn’t make them a writer.

To remember:

  • Programmable telecoms is your entire product, but is only a feature of mine. So don’t expect me to spend the same amount of energy digging into documents or APIs to find the two magical lines of code I need to solve the singular issue I have. Provide a direct path to solutions, with the deep dive as a secondary option.
  • A documentation product is not just the API. It should begin with a welcome page explaining the problems which the product solves, and how. It then also a step-by-step guide on setting up the platform, with fully worked examples of making API calls. It is a series of blog posts which show how to solve specific problems, combining two or more API calls. (See past TADHack winners for inspiring case studies.)
  • Most blogs are little more than glorified API examples. This is not a bad thing. Write them well, covering each step, and you’ll automatically include all the necessary keywords to be indexed by Google… thereby removing the urgency of writing that clever search algorithm for your API docs!
  • If your examples don’t scale, admit it! If you want to stop developers sending 1000 SMS by writing a for-loop, then provide a bulk SMS API.