Getting the Developer Experience Right

For all the abundance of APIs, there are multiple ways of getting a user up to speed with your product. The experience of learning how to use an API is very similar to that of using a consumer facing website or application. Indeed your conversion rate is likely to be higher if you remove as much friction as possible.

There has been a huge amount of literature produced to make those kind of consumer user experiences better, but only limited information about what the ingredients of a highly successful onboarding experience for an API product are. The principles are generally very similar, in particular the title of Steve Krug’s book from 2000 still lingers in my head as a mantra for developer experience design: Don’t Make Me Think.

We take the developer experience of our product very seriously, and while we think there is always room for improvement (cf Kaizen), we’ve spent enough time looking at this to realise a few things about what works, and what doesn’t.

People learn things in different ways

Teaching someone how to use a technical product is difficult because people learn in different ways. While some people prefer to read the entire API reference before writing a line of code, they aren’t necessarily trying to gain practical knowledge, and are often trying to get a sense of the tradeoffs and limitations before jumping in. Many people just want to find that first example they can copy and paste to see the thing in action.

Building a great experience generally means creating resources to cater for different kinds of people, but fundamentally distinguishing between users who are either pre-integration or post-integration. A common pattern for onboarding people looks like this:

• “Aha moment” (realise how powerful the product is)
• Initial integration (copying and pasting, a bit of modification)
• Exploration (working out what best practices are, what features are available)

It’s often only after the initial integration that someone will feel invested enough to learn about the intricacies of your product, and start applying the full power of what you offer. You may as well hide all that stuff until they are ready.

What you can provide

Providing a great experience means getting the following right:

• How-to Guides
• Reference Documentation
• Examples
• Developer tools

Ideally, a new user coming to your service should be able to follow a few simple steps to get to the moment of integration. Until that point you need to shepherd them, and in many ways protect them from the deluge of information you feel they might need.

Resources that tell someone how to do something are very different from resources which tell people what features are available.

Don’t write documentation for yourself

When you are an expert, it’s easy to create a mental anchor of how much knowledge your audience might have. Err on the side of caution, it’s usually better to over-explain than to under-explain.

Don’t make users wade through reference docs

Stick to the rule that a user shouldn’t need to browse your reference documentation to get started. You can make the experience much easier by focusing on enabling them to do stuff quickly. Hunting through reference documentation before you’ve integrated anything suggests a gap in your getting started resources. Your reference should only be a place to find best practices, method definitions and additional features.

Don’t be afraid to duplicate information

This is a really important point that trips people up. Programmers are used to the DRY principle, and find the idea of duplication inherently problematic. If something is said in a reference doc, surely it shouldn’t be repeated in your beginner’s guide?

To get round this, sometimes links are provided in a beginner’s guide to avoid repetition of reference material. However, this can lead to a rabbit’s warren of open tabs. The key is to see the beginners guide as completely separate from the reference. If possible it should encapsulate everything necessary to complete it. When people have finished with it, they probably won’t return, but it will have served its purpose. Your one goal with the beginners guide is to teach someone how to use a service or feature in the most efficient way possible.

Before adding any links, or extraneous information, ask yourself whether it helps the user with that goal. Don’t be afraid of including the same things such as configuration in each guide. Don’t assume that people have read previous guides, and that they have a certain level of knowledge. You can’t corral people into learning things in a certain order, but you can limit the amount of distraction they experience. People will leap into the thing that looks interesting and useful.

As a final point on the subject of linking in a beginner’s guide, it is perfectly fine to add links to content that gives a user more context about what they are doing, or that they can explore later. In this case you’re explicitly saying: “this is a simplified way of doing X, and you might want to explore better ways of doing it at this location”.

An additional danger

Many people will be content with a “good enough” understanding of how your product works. If your getting started guide tell people how to do things the “easy way”, a large percentage are likely to retain that information, or even the code contained in it. You can’t expect everyone to move onto the best practice stage. This is especially important if, for example, pesky things like security are left out of the initial picture. You have to work out what the balance is between getting people onboard quickly without leading them towards massive failure in future.

Help us improve

While we have put together this article about lessons we’ve learned, you may feel that we aren’t living up to these ideas in our own documentation. We know they’re not perfect, but we are open to feedback. The truth is that documentation is not a static thing, and needs to evolve with your service. There are always ways you can make things clearer for users.