The day you were longing for finally arrived. You deployed the first version of your API. Being able to see the result of months of hard labor feels gratifying. Your API is up and running. No errors. So you and your team go out to celebrate. The next morning, reality settles in. You start looking at analytics only to find out that usage is extremely low. Other than yourself, the developers from your team, and a couple of customers, no one really used your API. When you ask your team why there’s no usage, they can’t explain it. You published the announcement, users reacted positively, and the documentation website has been getting traffic. What’s wrong?
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
Developers don’t really understand what your API does. Examples that are too abstract, missing workflow information, and unclear capabilities create confusion about why operations exist, not just how to call them. Partners and integrators also don’t understand your API. They try to do a business evaluation of your API, but all they can find is a technical reference. Sales engineers don’t have better luck. Because there’s no clear use-case narrative, deals hang forever in the “what does this even do” stage. The support team can’t understand what your API does. Instead of instructions on how to respond to customers, all they see is a reference document full of jargon. Even product managers can’t fully understand what your API does. The documentation describes technical resources, not jobs-to-be-done. AI agents can’t understand your API. There’s no easy way to infer intent, meaning, or when to use one operation or another. No one understands what your API does.
The friction each group felt was a result of what they needed to get their jobs done. Naturally, not everyone went through the same challenges, as not everyone had the same task to complete. What made the API so difficult to understand? In summary, the problem lies in its documentation. But where exactly? It wasn’t its lack of technical detail. To answer where the problem is, we have to focus on what consumers need “to get their jobs done.” Each group felt that the API documentation wasn’t helping them move forward. The documentation was too technical and didn’t take into account the needs of each consumer persona. To fix it, you need to understand what each group really needs from the documentation.
You need to add use case walkthroughs that explain which scenarios the API can help with. Business users want to see information about capabilities and benefits that speak their language. Product users want to see user stories and the JTBD that each API operation solves. Support users want to see a list of FAQs for each operation as well as detailed troubleshooting instructions. Partners want to see commercial information and understand how they can make money with the API. Finally, AI agents want to see contextual information. How are you going to add all this information without overloading the documentation? A product manager wouldn’t want to see partner-related commercial information, for example.
One way to offer differentiated API documentation is to have multiple API portals. You could have a portal for developers, another one for partners, one more for support users, and so on. This gives you the maximum possible flexibility, as you can have a totally separate website for each set of users. But is it efficient? Well, perhaps if you’re maintaining just a couple of portals. However, if the number of portals grows, the effort to maintain everything becomes prohibitive. What I mean by “maintaining” is not just making sure that the portal is up and running but also updating it whenever you update the API. As the number of portals grows, the chances of having outdated information also grow. What’s the alternative, then? What I suggest is using a single API portal with a single OpenAPI source of truth. That OpenAPI document will hold the elements that are common to all audiences. Having access to it should be enough to know how to use the API. Now, on top of that, you add all enrichment each user group needs to understand the API. With OpenAPI Overlays, you can do it very efficiently. You would create one overlay document for each user group, adding the enriching elements. You could, for instance, make operation descriptions better suited for business users. Or add a troubleshooting section to existing operations. Or even add contextual information to help AI agents navigate the API. Each OpenAPI Overlay has its own document that you can maintain separately from the main OpenAPI file. As you can see, OpenAPI Overlays isn’t hard to use. I wrote about and shared examples here before:
So, using OpenAPI Overlays seems like a solid way to differentiate API documentation, right? While that’s true, there are costs in making it work. The first is related to keeping up with changes in the master OpenAPI document. Changes to your main OpenAPI definition can affect the behavior of overlays. Even though you managed to decouple the final documentation, it still depends on the shape of the initial definition. One other challenge has to do with the compilation that has to happen to render the documentation. That’s another piece of software that you have to maintain for every overlay. And finally, something less technical. What is the source of truth, in the end? Does the final documentation even make sense without the overlay?
On the one hand, using overlays can fit your API documentation to the needs of different user groups. On the other hand, though, making overlays work can be a costly adventure for you to embark on. You have to measure the costs you’re already incurring by not offering the best possible experience to your consumers. If those are higher than the effort of implementing OpenAPI Overlays, then you know what to do. If not, stick to what you already have.
