We explore where narrative, business-focused API documentation fits within our multi-dimensional value framework for developer portals. We then connect this to Generative Engine Optimization and explain why use case documentation is now essential, and also good for sales enablement.
Why do you need business documentation on your developer portal?
During developer portal planning discussions, API teams typically emphasize two main categories of requirements:
- Developer Experience: features that improve findability and discoverability, and shorten the time to the first 'hello world'.
- Operational Maturity: features that streamline approval flows by capturing relevant information early and automate the publication of technical and other documentation.
In addition to these, there is often an aspirational requirement that tends to be an afterthought: monetization. While monetization may not be essential from day one, for the long-term success of a portal it is important to ensure business alignment. Without this alignment, executives may lose interest, and once a program becomes overlooked, it eventually loses funding.
In our view, incorporating business documentation from the start provides three key benefits: it keeps the portal relevant to executives, enhances the visibility of your developer portal–or at least your ideas–in third-party genAI output through Generative Engine Optimization, and clearly communicates the value of your APIs and the services they support.
Using the value compass to receive better executive support
To help our customers focus on a well-rounded set of requirements, we created the Developer Portal Value Compass, a value model with three key dimensions: developer experience, operational maturity, and business alignment. Together, these elements help to achieve long-term devportal success.
Visual representation of the value compass and its three dimensions: operational excellence, developer experience and business alignment.
While all three value dimensions are context-dependent, business alignment is the most sensitive to the context of an organization. Each industry has its compliance requirements, and every company follows its own unique business goals. That is why an out-of-the-box developer portal will especially struggle to address requirements in the business alignment dimension.
Developer experience is most impactful when a developer portal fosters engagement and equips developers with the tools they need to achieve their goals effortlessly. This includes offering support, streamlining onboarding, and driving API adoption.
Want to gain deeper insights into your users? We help you meet their needs, elevate the developer experience, and drive both user value and business growth.
Operational excellence seeks to optimize workflows, to improve efficiency and scalability. Undefined manual processes can create bottlenecks, increase the risk of errors, and limit long-term success. In this dimension processes are made explicit, automated, and continuously improved to address evolving business needs.
Strategic business alignment is shaped by various factors, distinct for each situation. Business alignment covers the API program’s bright spots that show value to executives. A key consideration is to determine which API products should be made public, and how to position the API access within the broader business context. To achieve long-term success, we must align the developer portal’s KPIs with the overarching business priorities, thus ensuring that the API initiatives contribute meaningfully to the company’s strategic directions.
Even if it requires to step outside of the boundaries of the API program, aligning your developer portal with your company’s strategic business objectives increases executive support. Without this alignment, the portal may lose the sustained attention and resources it needs to reach its full potential. When executed well, APIs become a part of differentiation, helping your company reach and maintain a position of lasting strategic advantage.
Generative Engine Optimization
The way we nowadays search for and discover information about an organization and its API capabilities is changing: our search behavior is evolving to encompass both traditional queries and AI-driven discovery.
This, in turn, reshapes how organizations approach content marketing. Besides SEO, Generative Engine Optimization is also becoming important. The challenge lies in adapting the content to stay visible and relevant to large language models (LLMs), because:
- In a standard lightweight search query, only the few top results will be used to generate an answer.
- The answer is generated based on this top content, so instead of being able to influence people with a branded context, differentiated thought leadership or other content with a high level of perplexity needs to do the heavy lifting.
Generative large language models will try to answer questions based on their training data, which sets limits on the quality and relevance of their output. In web-enabled search and so-called “deep (re)search” queries, models also pull from external sources like knowledge bases or developer portals, in which case the accuracy and labelling of those sources matter even more than before, because the LLMs' answers to the user are stripped from the original context that might have given clues about the accuracy of the documentation.
Another important trend is that voice search is becoming more prevalent. And voice search queries are no longer constrained by the effort required to type something out. There is a different economy to the number of words people are using. Voice search questions are often more detailed and contextually specific. That means we need more detailed content that answers narrower questions to get picked up.
This makes search- and generative engine-optimized content even more important. The developer portal needs to surface better and more relevant content. One way to approach this need is to think about content depth and proximity:
- Content depth means thoroughly addressing specific use cases and giving compelling reasons for people to engage with your product. This includes detailed explanations, expert insights, and supporting data.
- Content proximity in a developer portal means making sure that business documentation is contextually close to the technical documentation, that explains how a business outcome can be achieved. So that it is more likely that your business positioning will be part of any technical content which gets retrieved outside of the brand context of your organisation’s web properties.
Explain the value of an API: use cases
Use cases are among the most valuable narrative content you can create, as they demonstrate how APIs and products can be used in real-life scenarios. They provide detailed documentation with varied terminology, increasing the chances that users will find the answers they’re looking for:
- GenAI models surface API information based on contextual relevance, so well-structured use case content helps ensure APIs are discovered in generative AI outputs.
- Clearly defined use cases with precise terminology increase the chances of an API being correctly recommended by AI assistants.
- Ensuring use case content is easily extractable (e.g., through structured data or well-formatted text) helps AI models retrieve and present it accurately.
Worked examples and business documentation also play a crucial role in sales enablement. Your organization's APIs as differentiating assets may not be fully utilized if your sales team is not comfortable talking about them with sometimes more technically fluent IT people on the other side. Help your sales team explain the value of your APIs by showcasing their affordances. Use tangible stories, illustrate with practical applications: this helps your site and your colleagues to communicate your APIs' value to both technical and non-technical stakeholders.
Do you want to know more? Get in touch with us and let’s discuss your use case.
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.
