In 2015, we published an article titled Why API Developer Experience Matters More Than Ever. And, if developer experience mattered more than ever back then, it matters even more than ever now than it did…then. (Wait, that makes sense, right?)

Much more than just a buzzword, developer experience is absolutely critical for user retention for software tools. But what exactly constitutes a great developer experience? You know a good developer experience when you see it, so nailing specifics down can be tricky. But not impossible!

At our Platform Summit 2023 in Stockholm, Kristen Womack, Principal Product Manager at Microsoft, spoke at length about improving developer experience through documentation, code samples, SDKs, and more.

Working on Microsoft’s Graph API, which has more than 5,000 endpoints in a unified REST API with more than 20,000 operations, it’s safe to say that Kristen has some experience with tackling issues like API sprawl and developing consistency across different services.

Five Pillars of DX

Without further ado, let’s look at some of the actionable insights she explored below. In her talk, Womack outlines (and expands on) five key concepts:

1. Moments
2. Hierarchy of Needs
3. Endowed progress
4. Consistency
5. Strategic writing for UX

We’ll touch on each of these below, but they’re all designed to combat the duality of developers that Kristen has identified time and time again: developers, she suggests, vacillate between modes of “I know exactly what I’m doing” and “I have no idea what I’m doing.”

This is problematic because it means that documentation and walkthroughs can go from overexplaining a concept to failing to provide the right information on a dime. The key, she repeats throughout her talk, is handing developers the right tool at the right moment.

She echoes Don Norman’s sentiments that “UX is how someone feels about themself when using your product.” In this case, that’s all about striking the right balance with information.

A great real-world example of this is the humble video game tutorial. When they’re done well, a tutorial should feel like an easy opening level. Ideally, it should reinforce a control scheme that’s intuitive enough to be picked up without the tutorial. If a player feels like they’re in a tutorial level, or the tutorial clashes with the control scheme, it’s doing a bad job.

Like a video game tutorial, an effective developer experience walks users through all the steps they need to know without overcomplicating anything so they can get started ASAP.

Magic Moments

In her talk, Kristen alludes to the 3:30:3 Rule for APIs:

Kristen Womack’s 3:30:3 Rule describes the ideal developer onboarding journey.

We’ve previously written about the importance of Time To First Call (TTFC) as a metric for measuring the health of an API. In that post, we reference Twilio’s ambition to “get [their service] up and running in 5 minutes or less,” which is echoed in the 3:30:3 Rule.

But Kristen points out that this rule only applies to the first couple of steps in the meta journey of an API’s use, which is really only going to happen once. In other words, developer experience extends way beyond that first experiment into the ongoing building and deployment of services using the API.

Developer experience is also, as Kristen highlights, a key part of developer evangelism. “Once they come to prefer your platform,” she says, “they champion your platform.” In this case, that could mean anything from talking with other developers about the API to writing blog posts about it or contributing to the upkeep of an open-source project.

When it comes to improving developer experience, “set it and forget” is not the right strategy.

Hierarchy of Needs

Adapted and inspired from the API Hierarchy of Needs by Bruno Pedro, as inspired by the work of Abraham Maslow.

Drawing on Bruno Pedro’s API Hierarchy of Needs, adapted from Maslow’s Hierarchy of Needs, Kristen presents a list of “must have”s for improving ongoing API usability…

• Website/portal
• Conceptual docs
• Reference docs
• Code samples
• Client libraries/SDKs
• Changelog
• Status page
• Known issues
• Test environment/data

…but she also acknowledges that this is “just a grouping of things until you create the experience around it.” So what, in practice, does that actually mean?

“We can make it [an API] look beautiful and navigable and all these different things,” Kristen says, “but…[we need to] apply this hierarchy of needs and really think about the first fundamental basic needs.”

To put it another way, no matter how flashy or fancy an API might be, its adoption will be severely limited unless it’s also usable and reliable. Therefore, start with the minimum viable product and worry about adding the really cool features later.

Endowed Progress

Kristen outlines research indicating that humans are motivated to “keep moving forward to complete a task they’ve already made progress on.” The perfect example? A humble coffee loyalty card that comes with a couple of stamps already added to get you started.

Of course, copying that approach in the context of application development isn’t quite as straightforward. It’s not, however, impossible. Kristen provides the example of a visual editor that she likes because it fires up with some developer-specific prompts filled in:

Code snippets or sample applications can go a long way toward accomplishing a similar feeling, especially if they have an interactive element. If you can hook potential users by showing them what your API is capable of, the odds are that you’ll hold onto them for a long time.

The sooner you can get users entering code and seeing what your API can do, the better.

Consistency is Key

Kristen underlines the importance of consistency when working on multiple products or APIs in this case. She refers to this concept as Familiar Hallways:

Familiar Hallways: consistency aids developer usability.

“Putting this in a view that feels familiar to people who are working across them is very helpful to know that you’re not lost, but also to know that for each one of these products or columns, you can still have a unique flavor to what you’re doing.”

Of course, this isn’t very applicable until you release multiple APIs, but it’s an endorsement for creating a system that’s easy to replicate as early as possible. Of course, the standardization of API documentation (offered by the likes of the OpenAPI Specification) can be extremely helpful with that.

“You must,” Kristen continues, “have consistency across all of your developer experiences. Otherwise, you’re not handing the tool at the right time when the developer needs it.”

The OpenAPI Map can help you find your way in the OpenAPI Specification.

“I like the OpenAPI Specification visualization,” she adds, “because it kind of shows you how this can become extensible, and how you can make your experience extend to other experiences outside of where your standard documentation lives.”

SDKs and Developer Experience

The benefits of using an SDK (and the drawbacks thereof) are hotly debated in this space, but Kristen compellingly argues that “how we consume APIs and how we use SDKs is changing.” How could it not be in the times of ChatGPT and ever-increasing automation?

A major problem with SDKs, Kristen suggests, is that users don’t always say what they mean when giving feedback about them. For example, “I don’t need an SDK because I know how to make HTTP calls” really means “I don’t want to learn yet another SDK,” while “I don’t know why I need it” actually translates as “I may not have handled rate limiting or expiring tokens.”

Meanwhile, hand-crafting SDKs is expensive and labor-intensive. Not to mention that multi-language development is required by default since SDKs must be idiomatic by language. This is a problem that Microsoft is aiming to solve with Kiota, an open-source project they’re funding directly, which builds SDKs, supports OpenAPI, and facilitates API discovery.

“To SDK or not to SDK?” is hardly the only question that API developers should be asking themselves. Still, it is a pertinent one, and the existence of tools to automate SDK production speaks to the ongoing efforts to improve developer experience in the space.

Strategic Writing and the Future of Developer Experience

In their 2022 State of the API Report, Postman declared the two biggest hurdles in the API space to poor documentation (this one took the top spot) and the difficulty of discovering APIs.

Womack emphasizes the importance of creating documentation that’s both human-readable (appeals to business decision-makers and developers) AND machine-readable (is SEO optimized with tooling integrations that use standards), since leaning too much in either direction can limit the potential impact of any new API.

There’s no doubt that, with the rise of artificial intelligence and automation, we’ll see changes to how documentation is implemented. But we’d be surprised if that didn’t include some of the API documentation solutions out there right now.

Ultimately, the success of an API hinges not just on its performance but also on its documentation, how it’s positioned, and other supporting resources around it. Only when you view all of that holistically you can really create a compelling developer experience.