Need someone to lead product management at your software company? I create software for people that create software and I'm looking for my next opportunity. Check out my resume and get in touch.

This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.

Development

The Components of A Developer Experience

Freshness Warning
This blog post is over 4 years old. It's possible that the information you read below isn't current and the links no longer work.

You’ve built an API or other developer tool but no one’s using it. People find it, but then don’t adopt it. That’s because you forgot the human element of the API: the Developer Experience.

How do you build a great developer experience? What things beyond the API do you need to design, build, and maintain? The best way to think about this is to think of your API as a product.

You wouldn’t build a product and then put no thought at all into how you take it to market, how you support it, or how people will buy it. But that’s exactly what happens with most developer tools and APIs. Someone builds it, writes some quick documentation, and publishes it to the world. That’s as far as it goes, and the API never becomes the raging success it could have been.

What do you need to create to build an experience that developers will love?

Vintage Fan Disassembly

Start with the API. A well-designed API is the foundation you must start with. No matter how good the rest of the experience is, developers won’t adopt your API unless it is well-crafted and easy to use, understand, and build on. If you need help with this, there’s plenty of articles out there about great API design. Study the APIs you love to use. What makes them great? If the developer can’t understand what an API call does by reading the plaintext API request and response, you probably don’t have a great API yet. The biggest mistakes that are repeatedly made in API design are in error handling, authentication, and consistency. Focus on doing well in these areas and you’re already ahead of the game.

But the API is just the product - what do you need to put around the product to make it a success?

How does a developer find your API? And when they do, how do they know what it does, if it’s going to be useful to them, and if they can afford to use it? Discovery is the first part of your developer experience that most developers will use. A developer that finds your tool needs to understand if it’s fit for their purpose. Right up front, you need to describe what your API is good for, not in vague, corporate-speak marketing terms, but using plain language.

Once a developer has decided to try your product, how do they get Support when they need to ask a question? Whether you provide an email address to ask you questions, a forum where they can ask other users, or expect them to fend for themselves on Stack Overflow, the support expectations should be explicit.

Don’t ship without giving developers a way to Try and Test your API. Depending on what your API needs and how it works this might be as simple as an API key or as complicated as a sandbox with mock data they can interact with. It’s best if the trial can be free. It’s hard to get a developer to pay to see if your API suits their needs. But even if your API product requires expensive long term contracts, the more you can reduce friction the better.

Your Documentation and Samples are more than just an API reference guide. Successful API products provide Quick Start Guides designed to show how to get up and running with various API features. They include in-depth tutorials on building real-world applications. They have recipes that show the right way to implement common use cases. And they do it all in several different programming languages.

The very best API products give developers a host of Tools and Downloads to make their development experience easier. The starting point of this is often a helper library, but other tooling can be useful. Some products include mock APIs for automated testing, command-line tooling, or even syntax and documentation plugins for popular IDEs.

Not all APIs need a Developer Portal but it’s the rare product that you couldn’t improve by adding one. Giving a developer a place to manage their API keys, see their logs, or view their support requests can help most API products. More advanced portals can contain interactive debuggers, configuration tools, and payment options.

And finally, no developer experience is complete without information that helps them Trust your API. Showing a developer uptime and past incidents can help them trust the reliability of your cloud API. And although it sounds counterintuitive, showing them security incidents and fixes helps them trust that your product is secure and has an active security response plan.

All these tools and information are the necessary components to build an API that developers enjoy using. These components help them decide if your API is right for them and help grow their usage. They make your API a well-rounded product.

More about the Six Principles of Developer Experience

Recently Written

A Framework for Scaling product teams (Oct 9)
The people, processes, and systems that make up a product organization change radically as you go through the stages of a company. This framework will guide that scaling.
Video calls using a networked camera (Sep 25)
A writeup of my network-powered conference call camera setup.
Roadmap Outcomes, not Features (Sep 4)
Drive success by roadmapping the outcomes you'll create instead of the features you'll deliver.
Different roadmaps for different folks (Sep 2)
The key to effective roadmapping? Different views for different needs.
Micromanaging and competence (Jul 2)
Providing feedback or instruction can be seen as micromanagement unless you provide context.
My productivity operating system (Jun 24)
A framework for super-charging productivity on the things that matter.
Great product managers own the outcomes (May 14)
Being a product manager means never having to say, "that's not my job."
Too Big To Fail (Apr 9)
When a company piles resources on a new product idea, it doesn't have room to fail. But failing is an important part of innovation. If you can't let it fail, it can't succeed.

Older...

What I'm Reading