Every API Company has Three User Interfaces

This was originally published on the Clarify.io blog, reproduced here.

When I joined Twilio in early 2011, I learned that API companies have three user interfaces:

First, there’s the website. It’s what we all think about because it’s the first thing most users see. We have designers, UX people, and similar who spend a lot of time making sure we’re using the “right” colors, fonts, navigation, user flows, and all the supporting elements.

Next, there’s the API itself. It needs to be logical, consistent, predictable, and a generally easy to use. There are lots of theories on how to gauge this but the easiest way is to listen for the “oh wow, that’s cool” or “OMG, what is going on!?” at hackathons or from friends and colleagues.

The third user interface is the documentation. This is where we run into problems. Quite often it is the most important interface but too often it’s left to last. Or worse, it’s written by people who have no clue what they’re doing.

Documentation as a User Interface

Consider a developer’s mindset when they look at your docs. They are in one of three situations:

They’re getting started. They may or may not have a clear idea of what you do, but they’re trying to figure out if you solve their problem and will help them go home on time. Or they want to know if you do something cool. For this mindset, you need to a) tell them what you do and b) show them how to do it. While you may have a few minutes to do the second step, you have only seconds to handle the first step.  Failure means the end of your relationship! In both cases, you need to be simple and concrete.

For the “what,” here’s our one-liner:

Clarify provides an API to help businesses build apps to Search and Understand their Audio and Video.

For the “how,” code samples win. That’s it. Don’t tell me how to use the system, show me. Give me something simple to do right now with little to no configuration. This speed with which this can be accomplished has been affectionately dubbed “time to first hello world” (John Musser, slide 42) within the API community. They will likely experiment and explore from here, but you need to get them started quickly and not distract and/or annoy them.

They’re building something. Whether they’re building the first thing with your API or the hundredth, they’re trying to accomplish something. It may be playing with that idea they’ve had or wrapping up that project for the company. There isn’t much of a difference. In this scenario – whether they acknowledge it or not – you are standing between them and going home, solving a bigger problem, or maybe even sleep!

In this case, you probably want to start from use cases or problem statements like

“I want to do X” and then show and explain the how. After that, add another layer or problem statement and grow this out to a more powerful and complex solution. Some people will get it right away and skip ahead, but some will want the information piece by piece. There’s no perfect answer.

They’re having a problem. Things go wrong. Believe it or not, sometimes API companies make mistakes. Sometimes developers make mistakes. That’s how life works. Unfortunately, in the throes of a problem, none of that is relevant. When they visit your documentation now, they’re frustrated, angry, and possibly panicked. It could be 3am.

Once again, we want to provide clear simple information describing the situation. But in this case, we need to provide specific error messages, response codes, etc that help them find exactly what they’re looking for and – more importantly – what they can do to diagnose and solve the problem. We should not default to trouble ticket  scenario. Having to wait till morning for an answer gives them many hours of annoyance, frustration, and time to research competitors. All of those are bad.

In all three situations, developers – also known as customers – are best served with documentation that is clear and concise, but also expressive. As API providers, we need to describe the problem and our solution in enough detail that customers and can turn and apply it to their own situation. Sometimes that will be incredibly easy, but don’t count on it.

As much as possible, step outside your team, line of business, or organization and put your documentation in front of people, solicit feedback, and listen to what people say.  Be prepared to be wrong. It’s only going to help you, your team, and your community.