What A Review of Banking Developer Portals Reveals About Technical Documentation

Most software developer portals were designed for people who had already decided to use a product. They arrived looking for implementation details, so the documentation focused on APIs, authentication, code samples, and technical reference information.

A recent review of banking developer portals by Pronovix, a consultancy that specializes in developer portals and developer experience, suggests that assumption may be creating new problems. The company evaluated the portals of eleven major banks to see how well they support AI-assisted discovery and evaluation.

Banking was a useful test case because financial institutions have spent years investing in APIs, developer portals, and open banking initiatives. The industry has had plenty of time to refine how it presents technical information to developers and partners. If gaps in context, discoverability, and content relationships appear in environments this sophisticated, chances are good they’re unlikely to be unique to finance.

As I read through the findings, I kept noticing how many of the issues sounded familiar. Missing context. Weak connections between related content. Technical information separated from business meaning.

Tech writers have been dealing with these challenges for decades.

Why Are Some Developer Portals Hard For AI To Understand?

Many of the portals reviewed contained substantial technical information. The problem wasn’t a lack of docs. It was that much of the documentation contained information focused on implementation while providing limited context about business purpose.

Many portals explained how a capability worked but spent less time explaining who it was for, what problem it solved, or when someone should use it. That distinction matters because implementation and discovery are different activities.

👉🏾 Someone who already knows which API they need is looking for instructions
👉🏾 Someone evaluating possible solutions is looking for context

Many portals seem to assume site visitors already know what information they need. That works well for implementation, but it works not-so-well for discovery.

What Is The ‘Semantic Gap’ In Technical Documentation?

Pronovix uses the term semantic gap to describe the distance between business language and technical language.

Marketing teams describe business value. Product teams describe capabilities. Technical writers explain how those capabilities are used. When that information is spread across different websites, repositories, and systems, the relationships between the pieces become harder to see.

The result is that readers must connect the dots themselves. Tech writers see this problem regularly. Users care about goals. Product teams too often focus on functionality. The docs we create frequently serve as the bridge between those perspectives.

The review suggests that AI answer engines face many of the same challenges. When use cases, audiences, business outcomes, and technical capabilities are loosely connected, understanding becomes more difficult.

Why Does Content Fragmentation Matter?

The review found that understanding a product often requires gathering information from several sources. A user may need to access one website to understand the business value, another to understand the product capabilities, a developer portal for implementation details, and a support site for troubleshooting help. The content exists, but the relationships between individual pieces are not always obvious.

This observation helps explain why tech writers spend so much time discussing information architecture, metadata, taxonomy, governance, and terminology management. Those practices help establish connections between related content.