This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.
Developer Experience Principle 1: Easy to Understand
Freshness Warning
This blog post is over 3 years old. It's possible that the information you read below isn't current and the links no longer work.
25 Sep 2020
To create a great developer experience, you must strive for a product that is Easy to Understand. You will not attract developers to your product unless they can understand it. A developer evaluating your product needs to understand what your product does. They need to understand what use cases it works for, and what things you don’t do.
Making your product easy to understand starts with discovery. 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. Because of the depth and complexity of APIs a developer can’t easily evaluate your product. Demos and trials are helpful but for a developer searching for a solution they may take more time than the developer has. Nothing’s more frustrating than having to write a bunch of code to figure out that the API doesn’t suit your purposes.
Right upfront, you need to describe what your API is good for. Not in vague, corporate-speak marketing terms, but in plain language.
If you’ve built an API for mailing and tracking packages the marketing folks might be tempted to write a big headline that says, "The Leading Parcel Logistics Management Solution." Marketing folks like big words that don’t mean much but mean lots of things at the same time. Don’t do that.
Help your developer discover what you really do. "Pay for shipping, schedule pickups, and track packages from one easy API. Pay as you go, no minimums, no extra fees." List what shipping carriers you work with. Or what countries you work in. Or whatever is relevant for your product. A developer came to your site knowing they needed to add package tracking to their web site. They can tell right away that this is something you do.
The language you use should be familiar to the developer. Using industry jargon makes the API hard for people outside the industry to understand. The technically correct term for something isn’t always what laypeople know it by. The package tracking experts designing your product know that freight shipments get a "PRO number" that’s used to track shipping progress. But a developer with no expertise in freight wouldn’t have any idea what this means. Call it a tracking number. To help the rare people who do happen to be a freight expert you can explain in the documentation. "For freight forwarding shipments the PRO number is the tracking number."
Don’t make up new words for things that already have a common meaning. Avoid the temptation to let marketing brand features or capabilities of your API. You have a widget that developers can embed to show package tracking progress on a map. "Maplet" is a super-clever name. Clever is the enemy of clarity. To be Easy to Understand, you need clarity in your terminology.
Using clever words increases the amount of thinking a developer must do to understand. Your documentation has the phrase, "add the Maplet to your page to show where the package is." They’ll have to go figure out what a Maplet is before they can understand what you’re telling them to do. But you could say, "add the package tracking map widget to your page to show where the package is." The developer now immediately understands what you’re talking about.
(Those marketing folks are really going to want to brand some of your features. Appeal to their budget. It’s going to cost money to brand those features. No one outside your company is ever going to call it a Maplet. They’re wasting budget they could spend elsewhere.)
A developer needs to understand your business model to determine if this fits within their budget model. Is it pay per use? Monthly fee? Free? Developers don’t want to talk to a salesperson to understand your product. Make pricing clear and up-front. Even internal tools have a business model. Why are you producing this, do you intend to maintain it, and what are the expectations for uptime? If you have usage limits, tell people that.
Understanding how the API works and if it fits into the developer’s toolset is another important part of discovery. Is this cloud, on-premises, an installed library? What languages do you suppor, and how do they work? Bite-sized code samples of no more than a dozen lines can help a developer get a picture of how they’d code with this.
Pre-built demos that show the API doing something and the code to make it happen can help. At Tropo, we made APIs for automating the phone network. We had web pages with a demo situation, a phone number you could call or text to see that situation happen, and the code that made it happen.
Developers will often want to go straight to the documentation to get a better understanding of the API. Documentation with only an API reference is missing a huge opportunity to help the developer understand the product. Different developers learn in different ways, so provide lots of different types of documentation. Quick start guides show how to build a basic hello world for a feature. Recipes for common tasks that chain together 2-3 API calls. Tutorials that build a larger, full-featured application. Screencasts that build the code and show it working.
All this should be right upfront in a place that a developer can easily find it. You’re helping them Understand your API, not making them go on a scavenger hunt. To achieve the Principle of Easy to Understand, seek to reduce cognitive overhead. Reduce the amount of thinking that someone needs to do. Make their first encounter with your product clear and easy.