Need someone to lead product or development at your software company? I lead product and engineering teams and I'm looking for my next opportunity. Check out my resume and get in touch.

Developer Experience Principle 1: Easy to Understand

Easy To Understand

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.

More about the Six Principles of Developer Experience

Recently Written

Developer Relations as Developer Success (Oct 19)
Outreach, marketing, and developer evangelism are a part of Developer Relations. But the companies that are most successful with developers spend most of their time on something else.
Developer Experience Principle 6: Easy to Maintain (Oct 17)
Keeping your product Easy to Maintain will improve the lives of your team and your customers. It will help keep your docs up to date. Your SDKs and APIs will be released in sync. Your tooling and overall experience will shine.
Developer Experience Principle 5: Easy to Trust (Oct 9)
A developer building part of their business on your product needs to believe that you're going to do the right thing for them and their customers.
Developer Experience Principle 4: Easy to Get Help (Oct 8)
The faster you can unblock a stuck developer, the better their experience will be.
Developer Experience Principle 3: Easy to Build (Oct 5)
A product makes it Easy to Build by focusing on productivity for developers building real-world applications.
How to understand your product and your market (Sep 30)
A customer development question you can ask to find out who your product is best for and why they'll love it.
Developer Experience Principle 2: Easy to Use (Sep 28)
Making it Easy to Use means letting the developer do everything without involving you.
Developer Experience Principle 1: Easy to Understand (Sep 25)
To create a great developer experience, you must strive for a product that is Easy to Understand. Reduce the amount of thinking that someone needs to do. Make their first encounter with your product clear and easy.

Older...

What I'm Reading

Contact

Adam Kalsey

+1 916 600 2497

Resume

Public Key

© 1999-2020 Adam Kalsey.