7 Mantras For Quality Developer Experience

Key takeaways from the 2019 Developer Experience LiveCast

Developer Experience is a crucial aspect of modern-day API ownership. With fierce competition between API providers in almost every industry, it’s no longer about what your API can do, but what it takes for developers to do. And yet, getting Developer Experience right still feels like 21st-century black magic to some…

In September 2019, we hosted a one hour webinar on Developer Experience, featuring two core community members: Emmelyn Wang — API strategist at Axway — and myself, Thomas Bush — tech writer at Nordic APIs. In this article, we’ll recap seven key takeaways from the LiveCast so that you can kickstart your organization’s DX journey with more than ten years of combined, in-field experience.


Our LiveCasts feature core community members on niche API subjects. If you would like to speak in a future LiveCast, contact us here.

1. DX is anything that makes it easier to use your API.

I kicked off my talk by answering the question, “what is a good Developer Experience?” While a good DX often includes comprehensive documentation, numerous SDKs/client libraries, and a witty, developer-facing Twitter account, that’s not all there is.

I put forward a new definition for Developer Experience best practices: DX is anything that makes it easier to use your API. Yes, complete docs and client libraries both fall under this definition, but it’s essential to recognize that there’s a lot more to it — we’ll discuss what later.

2. Customers will love you for ease-of-use — here’s why.

To explain the importance of Developer Experience, I referenced the 2019 Smartbear State of API Report, which revealed that more than 50% of consumers’ primary reason for using an API was speed or cost.

By improving the Developer Experience — in other words, by making an API easier to use — you allow the developer to do their job faster and, in turn, you enable the company to complete the project cheaper. Since speed and cost are some of the top reasons for using an API, you’re supporting customers in a way that’s meaningful to them by improving the Developer Experience.

Some consumers aren’t using an API for speed or cost, but integration needs. For these cases, think of improving the Developer Experience as an investment in customer satisfaction. You may not see results tomorrow, but long-term revenue gains are inevitable.

3. Always think outside-in, not inside-out.

Emmelyn’s DX strategy starts with a simple, but effective rule: think outside-in. Too many companies are guilty of thinking inside-out: they want to create an API, so they dive into the code and expose new functionality, without thinking of how that impacts things up- and downstream.

Instead, Emmelyn suggests you start with the consumer and work backward. This means building acute empathy for all of your consumers — even those you might otherwise neglect.

4. A positive DX starts with intuitive design.

Continuing with my thesis that Developer Experience means ease-of-use, I believe that building the best possible Developer Experience starts with intuitive API design. Many API providers focus entirely on additional resources — like docs, libraries, and walkthroughs — but not on the usability of the API itself, which should be the starting point.

When designing a new API, ask developer-conscious questions like “what endpoints will consumers need?”, “do endpoints take intuitive parameters and give intuitive responses?”, and so forth. By doing so, you’ll save yourself headaches down the line.

5. Reduce technical overhead, then build fallbacks.

Secondary to good design is reducing technical overhead. Make it easy for developers to use your API by 1) taking care of redundant/repetitive tasks, and 2) speaking the language of your developers (i.e., supporting your developer’s preferred programming languages). I borrowed these ideas from Adeel Ali of APIMatic, whose excellent ideas on DX I’ve covered before.

Only once you’ve appropriately designed and reduced unnecessary technical overhead should you worry about what I dub “fallbacks” — documentation, support channels, and more. While these items are all part of a good DX strategy, I put them second, since they’re most often needed as a consequence of poor design or excess overhead.

6. Documentation and sandboxes: get onboarding right.

One area where documentation is more than essential is onboarding. Emmelyn says you can set your developers up for success by giving them a clear frame of reference early-on in the onboarding process, making it clear what you can and can’t do with your API within the introductory pages of your docs.

Further to that, Emmelyn recommends designing your onboarding process with a clear goal in mind: for the developer to create fast, tangible value. For this, you’ll want to make walkthroughs, code samples, and quickstart guides easily discoverable on the main page of your documentation.

A bonus idea is to help developers track where they are during the signup process to avoid unnecessary frustration or confusion. Also crucial in early documentation is progressive information disclosure, which ensures you don’t overwhelm developers with unnecessary information.

Another crucial element in onboarding, says Emmelyn, is the sandbox. By giving developers a ready-to-go, test environment, you allow them to learn (and thus build) quickly — fulfilling the onboarding goal of creating fast, tangible value. With that said, make sure precise rules accompany your sandbox, so developers aren’t confused if production builds have conflicting rules.

7. Always iterate.

Finally, Emmelyn believes a big part of getting the Developer Experience right is iteration. By continually improving your developer portal, building new resources, and taking into account developer feedback, you can cover serious DX ground quicker than you think. During this time, Emmelyn recommends you practice communicating clear results so that you can ensure company stakeholders buy-in even during times of doubt.

Final Thoughts

There you have it: seven key learnings from the Nordic API’s LiveCast on Developer Experience. With all this helpful context — including what DX is and how to approach it — and plenty of specific recommendations — like what technical overhead to cut and how to onboard — you have all the essentials for an effective Developer Experience strategy.

To get the complete scoop on DX, be sure to watch the full Developer Experience LiveCast. Or, join the Newsletter for future DX insights.