A large, global financial solutions services provider based in the Netherlands (referred to here as the Company) and Pronovix began working together in 2024 through a technical writing discovery call. The initial audit included a high-level review, identification of potential improvement areas, and presentation of the findings. Pleased with the results, the Company decided to continue with a detailed audit and change plan.
The ultimate goal driving the need for professional consultancy was to enable the Company's developer portal users to seamlessly navigate from basic introductions to specific details, and to ensure the information the users need is always within a few clicks, no matter where they started their journey.
First Review and Delivery Method
After the introductory call, our assigned Technical Writer team members (referred to as Techwriters) gained access to the Company’s Azure-based developer portal and specific APIs. They used a visual collaboration tool to gather screenshots and organize them into a sitemap, which helped them better map out user journeys and identify possible blockers. The goal was to analyze the documentation and user experience, from onboarding through API integration.
The Company was pleased with the review and requested a detailed proposal outlining activities, milestones, support requirements, timelines, and costs. For efficient cooperation, we proposed a continuous delivery model over a timespan of twelve weeks.
Continuous Delivery Model
Based on our experience, working with the agile methodology within our continuous delivery model allows for client-focused work, collaborative learning with clients, and adaptive backlog management while ensuring flexibility and availability. It enables ongoing refinement and reprioritization of requirements, and provides more opportunities to discover what works best for the Company’s business.
Issues: Manual Maintenance, Blockers in Navigation, and Conflicting Divisions
The Company’s developer portal team used Confluence and Microsoft tools for storing, creating, and sharing content. While this setup has strong enterprise operations considerations behind it, it presents challenges to implement well-governed docs-as-code workflows on it.
Because the content was manually maintained across multiple locations, challenges arose with version control, consistency, and discoverability. Ultimately, the documentation management process proved to be insufficiently organized and was not prioritized. 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 primary challenges to address included:
- Navigation and onboarding issues: Key topics were missing from the main navigation and homepage. The onboarding guide contained broken links, vague or missing instructions, and unfinished chapters.
- Lack of clarity: Documented scenarios were incomplete, with workflows presented only through low-quality images without explanations or cross-links to relevant APIs and resources. Inconsistent terminology and missing key information further complicated user understanding.
- Product confusion: Products were not clearly distinguished as separate offerings with defined value but were instead presented as technical components.
- API interaction difficulties: API workflows involved multiple endpoints from different APIs, which were documented separately, making interactions unclear. Reference documentation lacked essential details, such as clear descriptions, definitions of terms, and comprehensive lists of recommended values.
- Lengthy onboarding process: Provisioning and onboarding were time-consuming, and required significant effort from both the Company and potential partner developers.
Many large organizations, especially those in compliance-heavy industries, can rely on inconsistent documentation workflows that have evolved organically alongside legacy systems. These setups can lead to inconsistencies, inefficient communication, and misalignment between divisions, making improvements challenging. Addressing these issues requires a comprehensive, structured approach and management support, with the aim to simplify processes while ensuring compliance and collaboration.
Evaluate your developer portal's UX and technical writing against industry best practices with a free, technology-agnostic assessment.
Solution: Technical Writer Services with UX Collaboration
The goal was to provide the Company with better documentation and content hierarchy—emphasis has been added on minimum viable documentation: onboarding guide, API reference, and API overview. The Techwriters set up bi-weekly milestones and relied on the flexible Kanban methodology to enable smooth workflow on the project.
Our Technical Writers ensure a thorough content audit, clear content strategy, content creation and enhancement, information architecture, and maintenance.
API Documentation Enhancements: API Flow Guides, API Reference, and Onboarding Guides
In collaboration with the developer portal’s product owner, the Techwriters reviewed the onboarding guides and, with support from one of the Company’s lead architects, gained insight into the API architecture. One significant hindrance we were to smoothen out was this: During customer onboarding, the lead architect used to have to repeatedly clarify key integration steps for each new customer. This need for direct support was ultimately due to insufficient content quality and disorganized documentation management.
To solve this issue, a new content type documenting the API flow guides/Use case tutorials was introduced. It provided step-by-step instructions covering the most important use cases of the APIs with cross-links to the detailed API reference docs, aiming to help users understand how to consume the APIs, shorten the onboarding period, and reduce the support burden from the Company.
The layout of API reference document pages was also planned for improvement, including a 'Download Postman collection' button, links to related API flow guides, and a tab-switching mechanism to publish related but auxiliary content on new pages, reducing clutter and keeping the API reference focused.
The onboarding guides were also enhanced with actionable steps and links to the next phases. All onboarding materials and user manuals were placed under a single menu, where users could find detailed information about various topics.
The Techwriters focused on long-term process improvements by introducing tools and best practices, such as recording meetings for reference and for compiling terms, descriptions, and rules to create a developer portal style guide for the Company.
After gaining enough insights about a typical API consumption flow, the Techwriters created templates to help standardize documentation and maintain consistency.
Sitemap Improvements: Target Audience, Business Goals, Service Catalog and Cards
With support from Pronovix’s UX Researchers, the Techwriters contributed to redesigning the site's content organization and navigation, starting with a target audience and best practices research.
A collaboration with the Company’s marketing and sales team was also necessary to incorporate the previously overlooked business user perspective into the developer portal's content scope.
The Techwriters prepared two static sites for A/B testing. In the navigation, they ensured business pages remained jargon-free while providing access to business use cases, technical API flow guides, and API references. They also structured the documentation to allow seamless navigation between different content types in all directions.
They also provided the Company with a Service catalog to cater to the business audience’s needs. Service cards have been planned with descriptions and tags to allow users to easily find information about a service: including benefits, business and technical use cases, with links to implementation guides and API references.
Outcomes and Lessons Learned
The new sitemap and content architecture were designed to address existing issues and enhance the user experience by providing richer content and smoother navigation for both business and technical users.
The Techwriters' reports and change suggestions were valuable to the Company and delivered ready to be implemented. As the Company highlighted, they were pleased with the Techwriters’ responsiveness and how they contextualized the developer portal's issues within their industry.
This project highlighted that achieving long-term success goes beyond immediate solutions: it requires the consistent adoption of the right tools and methods across the Company. While legacy systems and fragmented processes present challenges, a strategic approach to content organization, UX design, and agile collaboration can pave the way for long-term improvements. Once the goal is defined our diverse team of experts can provide support and help to adopt the right tools and methodologies.
"Our approach isn’t just about providing a one-time solution but equipping the company with the tools and guidelines necessary for sustained success in their documentation efforts.” - Ádám Balogh, Technical Writer, DocOps Engineer at Pronovix.
Explore our Techwriting and UX Services to see how we can help or drop us a line. We can assemble a team from our experts with diverse specialties tailored to your needs.
