Let’s start with a quick exercise: think of the person who will be consuming your API documentation. You’re likely picturing a developer who’s looking to plug into your API. Generally, it’s wise to position your developer portal with this person in mind.

That person is not, however, the only person who’ll be looking at your API and its documentation. In fact, Postman reported that only half of those who work with APIs have a role related to development.

Other roles identified in their research included, among others, CEOs, support agents, and data analysts. In other words, all sorts of people are trying to figure out what makes your API tick. And the size of several of these groups is rising year over year.

If you ignore these people, you risk your API being overlooked in favor of one that explains its purpose more clearly — even if yours would be much better for the job at hand.

The issue of the day? How to ensure your API appeals to different audiences without compromising on the technical information that API consumers and developers need. So, without further ado, let’s get into how key players in the market are doing just that.

Keep It Simple… (ft. Zapier)

Make no mistake: using an API to integrate with another service is not a simple task. It might be easy for an experienced developer, but that’s not quite the same as being simple.

That said, using clear and straightforward language can make the process simple to understand (to some degree, at least), even for those who wouldn’t actually be confident consuming an API or writing code. This is something that Zapier does really well.

Zapier spends nine whole sections covering how the platform works without (for the most part) getting into any code. The platform isn’t no-code in the way that something like IFTTT is, but it explains Zaps in a way that even those without technical knowledge can understand.

And the fact that Zapier has millions of users across diverse spaces like real estate and education, as well as software and IT, is a good indicator that their approach is working.

…Or at Least Make It Look Simple (ft. Twilio)

Twilio’s documentation, on the other hand, jumps in at the deep end — click on any of the APIs in their developer portal, and you’re taken right into code samples and HTTP status codes:

Granted, Twilio is atypical in that it’s an API-as-a-product. It doesn’t necessarily need to spend much effort catering to a non-technical audience because it’s unlikely that such an audience would find their own way to it.

What the site does do, however, is mimic the minimal visual style of popular SaaS products. Even if the language of the documentation is unfamiliar to a non-technical audience, the look and feel of the site certainly will be. And that makes it feel less intimidating.

In addition, the site offers a range of tutorials down the side of each API’s documentation hub:

These were probably implemented in this way to be useful for SEO. Still, they serve another purpose: giving non-technical readers quick insights into whether or not the API can be used to reach their desired outcome.

Choose Your Words Carefully (ft. MailChimp)

In a move that’s not uncharacteristic for them — remember the attention the brand got just by riffing on their own name? — MailChimp leverages the power of words, starting with their high-level summary:

The trend of using clear, concise language continues throughout their developer portal.

In fact, only once you’ve really zeroed in on what it is you’re trying to do (and have made your way through the introductory content) does MailChimp break out the code samples.

And it’s important to note that the portal does so without creating unnecessary roadblocks for a technical audience that’s ready to jump right in and start using the API. All of this content is as useful for getting them to the right place as it is for helping newbies get the lay of the land.

There’s much more to building a great documentation developer experience than simply dumping code snippets somewhere. MailChimp’s documentation really highlights what great technical writing is, combining expertise with an informational approach that verges on storytelling.

Let Users Get Their Hands Dirty (ft. Opayo by Elavon)

Providing a sandbox for API consumers is nothing new. In fact, they’re a great way to improve developer experience and allow would-be API consumers to take your service for a test drive with no strings attached.

What a sandbox doesn’t always do, however, is let non-technical audiences get a feel for how your API works. “Why is that a problem when they won’t be the ones using it?” you might ask. The answer, of course, is that they may have the final say on purchases…

Creating an API demo is a great way to let potential buyers, even if they couldn’t build with it themselves, get a flavor of how an API works.

Opayo has a nice demo of how their Shared API can be used to carry out secondary transaction types, simulating a merchant’s transaction management system:

The demo provides proof of concept for an audience that may otherwise struggle to visualize how the API will be implemented. Although you’ll only ever be able to scratch the surface of what’s possible with your API in a demo, that could be enough to close the deal.

API Audiences Will Only Get Wider

In 2022, RapidAPI’s Kelsey Mullins reported that 90.5% of developers expected to use APIs as much as or more than they did in 2021. But it’s worth noting that, in most cases, these developers won’t be operating in silos.

The same study found that 98% of enterprise leaders agree that APIs are an essential part of an organization’s digital transformation. Do all 98% of those enterprise leaders understand how APIs work and how to implement them effectively? That’s less likely.

There’s a gap to be bridged between developers and non-technical (or less technical) executives, and successfully doing so will require input from many different parties. Fortunately, many of the tenets of writing good documentation can help on that front:

• Using clear and concise language to summarize aims and functions
• Improving discoverability and searchability, such as with a table of contents
• Providing showcase demos (as well as code snippets) when possible
• Avoiding technical terminology unless it’s required
• Streamlining your content and keeping it up to date

Developer portals that are truly effective and accessible might even convince a few decision-makers that your API is as much of a vital investment as the development team claims it is…