What A Review of Banking Developer Portals Reveals About Technical Documentation
A review of banking developer portals found familiar documentation problems hiding behind modern AI concerns
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.
What Happens When Important Content Is Hidden Behind Login Walls?
Organizations often place valuable information behind registration forms and authentication barriers. The issue isn’t whether the content exists. The issue is when it becomes available. If important information appears only after registration or authentication, it can’t help visitors understand, compare, or evaluate options during the discovery process.
Does Technical Documentation Influence AI Recommendations?
Documentation is not the only factor that influences whether a product or service appears in AI-generated answers. However, documentation contributes evidence.
When documentation clearly explains capabilities, audiences, use cases, business goals, and implementation details, there is more information available to support understanding. When content focuses almost exclusively on technical specifications and procedures, there is less context available.
Good docs have always explained more than how to complete a task. They help readers understand purpose, relevance, and relationships between concepts.
What The Findings Tell Us
The findings reinforce many principles tech writers already advocate for:
👉🏾 clear terminology
👉🏾 strong information architecture
👉🏾 useful metadata
👉🏾 well-defined audiences
👉🏾 practical use cases, and
👉🏾 content that explains purpose alongside procedure
None of those practices were created for AI. They exist because people need context to understand complex information. The review suggests that AI tools benefit from many of the same signals.
Reading through the findings, it is difficult not to notice how many of the observations map directly to challenges tech writers have been discussing for years. Missing context, disconnected information, inconsistent terminology, and weak relationships between content assets are not new problems. The review simply shows what happens when those problems are examined through the lens of AI-assisted discovery. 🤠