10 Common Mistakes in Developer Experience

Hoss@hossapp /

You've created a fantastic API for public developers. Great! The work doesn't stop there. You have to make a developer experience to draw developers into using that API. Not only that, but you've got to maintain that developer experience if you're to have any hope of retaining those developers. No need to be daunted by the projects before you. Many have walked this path before, and you are in the fortunate position to learn from their past mistakes.

We've compiled ten mistakes we often see with API experiences:

  1. No Getting Started Guide
  2. No Clear Developer Journey
  3. A Pay-to-Play Service
  4. An Over-Involved Sign-up Process
  5. No Sample Apps
  6. Limited Programming Language Support
  7. An Outdated API Reference
  8. Not Writing Blog Posts
  9. A Hard-to-Navigate Website
  10. A Minimal (or Nonexistent) Developer Dashboard

Let's get right into it and look at why your developer experience suffers when you have...

No Getting Started Guide

For many, this is an obvious mistake in hindsight. You've made a wonderful API, and you think developers will love using it. And you may be right! Unfortunately, developers aren't going to use your API if they can't even get started.

The many obvious aspects of your API are that way because you already have experience with it. Take a step back and think about what someone completely unfamiliar with your API needs to get going. Spell it out for them. By doing so, you'll make it easy for them to get hooked on your product.

And speaking of providing a getting started guide, it can be confusing when you have...

No Clear Developer Journey

Do you know what can be just as confusing as an API with no getting started guide? An API that is unclear what is needed at each stage of integration. If you’re making this mistake, you have information spread out in multiple places with no real guidance between them. Developers aren't going to waste time figuring out what your API does, how it helps them, and how to continue their journey.

You not only want a guide to get them started, you want to show new developers that’s their most important step. Wherever possible, reduce the friction—not only for the first experience, but throughout development. After initial success, make a clear call to action for potential next steps, including common and valuable use cases.

It’s hard to get developer attention, so do your best to keep them once they’ve found you. One of the biggest places of friction is to push the business side before they’ve had a chance to evaluate what’s possible. It's hard for developers to understand an API when you have...

A Pay-to-Play Service

Let's get this out of the way: we understand you need to make money off your product. It's a business, after all! That's not the problem. The problem is making a developer put in their personal credit card or talk to sales just to try your API. Because, honestly, many developers aren't going to stick around when so many other APIs disappoint.

Regardless of their reasoning, developers appreciate having at least a little leeway to play with the API free of charge. What this looks like depends on your API. Some options include making specific API calls free-to-use or having a free-tier usage limit. At a minimum, include a self-serve free trial.

Then, after trying out your API, developers will be more willing to sign up and pay you. That is unless you have...

An Over-Involved Sign-up Process

Once convinced you can solve their technical problem, developers will be eager to begin paying for your service. They go to sign up, only to be presented with that sales discussion they’ve been avoiding so far. You may have ensnared many with their sunk costs, but others will look for immediate self-serve options.

What could have been a simple onboarding process has now become unnecessarily drawn out. Make it quick and easy to sign up. If possible, make it so a potential customer doesn't have to talk to anyone to use your product. Developers are friendly people who enjoy conversations, but they’ll be annoyed if those discussions aren’t necessary.

Once they're signed up to access your full product, your work doesn't stop there. Developers will run into some roadblocks if you have...

No Sample Apps

The step from a getting started guide to a real project can be a big one. In many cases, they can get lost in the weeds of your API trying to move beyond Hello World. You can address this by providing sample apps that use your API.

Many developers learn by example. They like to see something working, which can be the quickest way to convey complicated ideas. Your sample apps pair specific use cases with programming languages or frameworks. They give all the code needed to stand up the example, plus a tutorial to help guide developers to success. With multiple sample apps, you can cover a wide range developer problems and help out a large portion of your customer base.

While we're on the topic of reaching out to as many developers as possible, we should also touch on how it can be advantageous not to have...

Limited Programming Language Support

To truly know what languages your developers want, you'll have to research the field your API is within. That being said, you can bet developers have programming language preferences for integrating with your API.

By providing SDKs for multiple languages, you increase the likelihood of developer adoption and developer retention. Developers aren't going to change how they build their apps just for your API; make your API compatible with as many languages as possible.

Merely supporting multiple languages isn't enough, in any case. You'll want to maintain comprehensive documentation for your API and its SDKs. Developers will quickly grow frustrated with...

An Outdated API Reference

Your API will change over time. That's natural, of course, but it can create some problems with your documentation. Merely creating an API reference is not enough, as it will quickly become outdated unless you maintain it.

Developers aren't going to want to waste their time trying to troubleshoot why their calls to your API have suddenly stopped working. By keeping your API reference updated, you can ensure developers using your API stay updated as well.

Many struggle with informing their users about new features and changes. Why is that? Well, it's because they are...

Not Writing Blog Posts

APIs aren't static, and your developer experience shouldn't be, either. As your API changes, developers will greatly appreciate you keeping them updated. A great way to do so is with articles written for your technical audience.

Blog posts give you the freedom to add additional information you feel developers need to know. You can just use a blog to inform them about new features in your API, but you can also use it as an opportunity to provide short narratives showing how to use those features. If your API reference explains how the API works, your blog posts can go into detail about why that matters.

Narratives are a great way to help developers understand the content. Of course, that assumes they can find the right content. A common mistake we see is having...

A Hard-to-Navigate Website

We've mentioned many types of content: blogs, getting started guides, API reference guides, and more. All of these are beneficial landing hubs for different types of content. A developer will see you have a blog and know they can find updates there, for example.

None of that matters, though, if developers can't find the pages. The problem is enhanced when you’re catering to other audiences beyond developers, as well. Too often an API becomes a technical afterthought, sometimes not included at all within navigation. A great developer experience makes it easy for developers to identify the right place for them without clicking through 11 pages to find it—or worse, Google searching your own site.

Sometimes this disjointed experience continues even after developers find your documentation. That’s because many APIs have...

A Minimal (or Nonexistent) Developer Dashboard

Your API documentation is typically static, but developers want a personalized experience. One reason that Stripe and Twilio get such good reviews from developers is that they make it easy to inspect your own account.

A developer dashboard lets you review API keys, errors, logs, and other details that will change based on the user. The clearest documentation in the world won’t help a developer make a call without credentials, for example.

Fortunately, you don't have to build all of your developer experience on your own. Reach out to the us so we can show you what we’ve built.

Subscribe to Hoss ModeA weekly newsletter with curated articles, community discussions, news and trends.

Case Study: Why NewCraft Chose Hoss to Revamp its Developer Docs

Read more
NewCraft wanted its excellent developer experience to be a differentiating factor for its business. While other docs tools are templatized, Hoss provides companies with the tools and support to create entirely unique experiences that align with their business and use cases. This meant that NewCraft’s developer portal and documentation would be created for its specific needs and audience instead of looking the same as every API other company, which was appealing to NewCraft.
Back to blog

Copyright © Hoss Technologies, Inc. 2021 - All rights reserved. Terms of Service & Privacy Policy