This talk was presented at the AI The Docs 2025 online conference. We are thrilled to share the recording and the summary with you.
Visit the talk summary page to see all of the presentations from the conference.
presentation
Ádám Balogh (Technical Writer, DocOps Engineer at Pronovix) and Kathleen De Roo (Information Architect & UX Researcher, Head of Service teams at Pronovix)
Summary
Why do AI and advanced search solutions often fail to deliver useful results on developer portals, even with significant investment? How can teams better collaborate to achieve AI readiness?
In their presentation, Ádám Balogh (Technical Writer, DocOps Engineer) and Kathleen De Roo (Information Architect & UX Researcher, Head of Service teams at Pronovix) argue that developer portals need a holistic approach to UX and technical writing to prepare for AI. Silos between teams result in broken user journeys, unfindable content, and unusable foundations, problems AI cannot fix.
Key insights:
- The foundation problem: Even with advanced CMS and AI search, portals fail if metadata, structure, and content quality are poor. Machine-unreadable PDFs, broken URLs, and inconsistent IA make both human and AI search unreliable.
- AI as a new user persona: Treat AI like a user who consumes content on behalf of humans. An AI persona card helps clarify its needs: structured, accurate, predictable, accessible content. AI doesn’t see interfaces (it sees structure and text).
- Align UX and tech writing:
- Writers must join UX discussions early.
- Create sitemaps jointly to unify flows and content.
- Apply a content-first approach in wireframes.
- Establish shared feedback loops (usability, accessibility, readability).
- Core principle: “You don’t need perfect tools, just better collaboration.”
- Practical actions for AI readiness:
- Prioritize high-value docs (API references, onboarding, overviews).
- Audit content for accuracy, gaps, and relevance.
- Strengthen hierarchy, metadata, and clean URLs.
- Improve internal linking to guide humans and AI alike.
- Convert legacy PDFs/Word to structured formats (Markdown + llm.txt).
- Future directions: Standards like MCP and Agent-to-Agent (A2A) point to “super assistants”: agents that call other agents. But they will still depend on clean, structured, high-quality content.
As Ádám and Kathleen underlined, bad foundations create clumsy AI. The path forward is breaking silos and fostering collaboration across UX, writing, marketing, and API teams.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.
