How have user needs shaped developer portals over the years, and what can we do to prepare for the challenges brought by generative AI? In this article, we explore the collaboration between UX and technical writing teams, and the obstacles one can face as AI becomes an integral part of the developer experience.
[Note: In this article, “AI” primarily refers to generative AI tools. The content is based on a presentation and a webinar by Kathleen De Roo (Information Architect & UX Researcher, Head of Service team) and Ádám Balogh (Technical Writer, DocOps Engineer), and has been paraphrased and summarized by Klaudia Jancsovics (Content Writer & Editor).]
From API catalogs to complex business needs and content types
When we started our journey with developer portals, they were little more than browsable API catalogs and the audience was mostly developers. For this reason, documentation was technical, minimal, and often written by engineers as a side task. However, both the audience and the business needs have been changed: content had to be broadened and user experience had to be upgraded.
As portals evolved, content such as guides, tutorials, and use cases became essential players: developer portals transformed into self-service ecosystems for onboarding users, supporting product adoption, and driving business outcomes.
While developer portals have come a long way, we still often see teams working in silos behind the scenes. In our experience, these disconnects become even more pronounced when AI comes into the picture.
Design without content is hollow and content without structure is invisible. Both fall short unless usability and information architecture are treated as shared responsibilities within the teams. For example, challenges arise when UX designers create intuitive flows without accounting for content requirements or when technical writers produce clear, relevant documentation without insight into user personas and their journeys. Without close collaboration, even well-executed work can result in a fragmented developer experience.
Lessons learned from a disconnected documentation strategy
One example that illustrates the importance of foundational content practices comes from our work with a large global provider of financial services. Like many enterprise organizations, they maintained documentation manually across multiple locations, which led to issues with version control, content consistency, and discoverability. While such situations often evolve naturally over time in large companies, a lack of dedicated budget for documentation and processes will inevitably hinder the developer portal’s usability, onboarding experience, and overall developer satisfaction.
The company made a significant investment in a powerful search interface where the system included categories, filters, and drill-down capabilities. Their CMS also supported structured content, metadata fields, and relationships between documentation pieces. However, in practice, the search functionality fell short as results were often irrelevant or entirely missing.
In response, the company turned to AI (specifically, retrieval-augmented generation [RAG]) models hoping that generative tools could bridge the gap and provide better answers. Ultimately, the tested tools failed to return meaningful or accurate responses.
A closer look revealed that the foundation was missing because:
- the content team had not implemented meaningful metadata,
- the information architecture lacked consistency,
- broken URLs disrupted content relationships, and
- key information was locked away in PDFs stored in an external system out of reach for both users and AI tools.
This experience underlines a core truth: no single team can deliver a successful developer experience in isolation. And while AI can seem like the ultimate solution, it cannot compensate for missing or unstructured content.
Designing for a new user persona: how information architecture meets AI
When setting up the information architecture of a developer portal, our UX team aims to reflect a company’s unique context: its business goals, user expectations, and long-term strategy. Well-done content structure and navigation help to enable meaningful interaction.
AI as an intermediary user
Traditionally, we focused on human users, but now AI is starting to participate in the user journey as a persona in its own right. It gathers and interprets content to generate answers, recommendations, or insights for others. In this way, AI becomes a kind of intermediary user: it consumes to provide.
This shift challenges us to rethink our approach. To serve this new user well, we must ensure that our portals are structured, annotated, and interconnected in ways that AI can understand and use effectively.
When we treat AI as a persona, we can list its characteristics, needs, typical behavior, and the way it will interact with the portal.
A persona card can help us understand if the decisions we make around organizing the sitemap and setting up content will benefit or hinder users. In this case, the user is AI.
The image below is a small segment of our AI Persona card. For the full version, click on the image and follow the steps.
Designing for generative AI
The output provided by any generative AI is only as good as the structure and content it relies on: it does not work without clear, structured, and meaningful content.
AI should be able to:
- consume through predictable and clear structure, and accurate information,
- recognize and find relationships, dependencies, and semantic markers, and
- follow an accessible layout and content (with the help of alt text or captions).
We cannot just add AI as something new to the portal, we need to make sure that what we have is prepared for it. For this reason, AI becomes part of the whole user experience design: UX and technical writer teams need to align more than ever to build developer portals that are not only helpful to human users, but are also interpretable by machines, laying the foundation for AI-driven services.
Collaboration between UX and Technical Writer specialists
What might a fruitful collaboration look like? At Pronovix, we focus on the following areas to ensure that both UX and technical writer specialists bring their expertise:
- Early UX discussions: define user needs, business goals, and requirements for the next developer portal iteration.
- Sitemap creation: ensure that user flows and structured content go hand in hand.
- Early content audit: identify the existing materials and uncover what might have been missing before the project enters the design phase.
- Content to drive wireframes: use existing content to shape the wireframe.
- Iterative feedback loops: test usability, readability, and comprehension.
- Final QA (human + AI) and Accessibility review: ensure the portal works for people and machines.
We join forces to ensure better outcomes for every user. Even if our teams are not in the same meetings, we still work from a shared roadmap. If you are a UX designer, involve your writers early: collaboration from the start is key. Long-term success is impossible if the specialist teams are stuck in silos.
5 practical steps towards AI-readiness
As we highlighted in one of our articles, one does not have to start from scratch to be prepared for AI-augmented tools. The following five steps can be a guide.
1. Prioritize high-impact content (apply the Pareto Principle): Focus on and make machine-readable the minimum valuable documentation, such as API reference, onboarding guides, and API overviews.
2. Have a targeted content audit: Collect an inventory to know what you have, gather data to better understand what is used, what is confusing, and what is missing (analytics, support tickets, and user feedback are valuable resources). Then, analyze the data, check accuracy, relevance, usage, find gaps, and examine the editorial process itself. Finally, apply changes based on what you learned.
3. Strengthen content hierarchy and metadata: This is fundamental for humans to find what they are looking for and for AI to process the details. For example, URLs without generating nodes can lead to confusion, whereas clean predictable URL aliases help humans and machines understand where the given topic fits by showing parent relationships clearly. Adding clear and rich metadata tags, categories, versions, features, or supported product names are also important.
4. Make content discoverable - Internally and for AI: Good linking not only guides users, it helps AI models understand topical clusters.
5. Convert legacy content to structured formats: Legacy documentation often lives in PDFs, Word files, or wrapped in unstructured HTML. For example, converting old HTML pages to Markdown can make a difference as Markdown is five times more token efficient than HTML.*
To put the difference into perspective, we calculated the number of tokens in different formats needed to transmit the same information using the GPT-4o & GPT-4o mini Tokenizer:
- The original HTML version of a web page contains 40 988 characters, which breaks down into 11 184 tokens due to its heavy use of tags and styling elements.
- After converting the same content into Markdown (preserving only the essential structure and meaning), the size drops to 6 577 characters and just 1 580 tokens.
A few best practices:
- Periodically import or sync the key external PDFs into your portal.
- Extract and index your content in a structured way.
- Present users with summarized or previewed content with the option to open the full PDF.
- Bonus: Use AI to enhance content quality.
Model Context Protocol (MCP) and Agent-to-Agent Protocol (A2A)
MCP and A2A are protocols for AI interoperability: the first connects agents to tools, APIs, and resources with structured inputs and outputs. The latter facilitates dynamic multimodel communication between different agents as peers.
In the future, MCP and A2A communication can go further and become the foundation of super assistants. Once these new assistant types arrive they will radically change how developers interact with APIs, technical products, developer portals or any kinds of (web) interfaces.
These agents won't just suggest documentation or solutions: they will be the interface. So there will be no traditional UI, nor traditional user journeys, just bots calling bots. Instead of browsing a developer portal, for instance, users will talk to an assistant.
There is a catch: no matter how smart these assistants get, they will still be completely dependent on the quality of the content they are built on. If one does not fix what is broken, clarify what is the structure, then even the most powerful assistants will stumble, they will guess and hallucinate.
As AI becomes a more active participant in how users access and interact with content the role of UX and technical writing specialists becomes even more critical. Their collaboration is not just a nice-to-have, it is a foundational requirement for building developer experiences that are both human-friendly and machine-readable.
Clear structure, purposeful content, and intentional design are what enable AI tools to function effectively and deliver real value. Without this shared effort, even the most advanced technologies will struggle to make sense of what is missing.
“We're building the future, but it runs on today’s forgotten pages.” - Ádám Balogh, Technical Writer and DocOps Engineer.
Fill out our technology-agnostic assessment, receive actionable insights to enhance user experience and documentation quality or contact us if you need help.
Curious to learn more? AI The Docs 2025 recordings are now available for a small fee.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
