At the heart of this article are two terms that sound similar but serve different purposes: discoverability and findability. They are not new but gaining renewed importance as user experiences evolve from search engines and navigation menus to chatbots and AI coding assistants.
What does discoverability and findability mean in the context of developer portals? And what can we learn from standout API portals doing it right?
Corporate developer portals are not one-off technical or publishing solutions, but socio-technical hubs built for business value and optimized across many dimensions, user experience among them.
For nine years now, we have been hosting and organizing both the Developer Portal Awards and the API The Docs knowledge-sharing event series, with the purpose to collectively explore and advance the evolution of documentation and developer portals.
Beyond offering practical examples and inspiration from among the award nominated portals of the past two years, this article also carries a core philosophical message: user intent is the crux, never lose sight of it. User experience trends and solution methods evolve rapidly, with new approaches constantly emerging. But the user’s need remains the innermost cogwheel driving it all.
Table of Contents:
- What is the Developer Portal Awards?
- Discoverability and Findability
- Common search experience antipatterns
- Examples for your inspiration
- Explain what you do around here
- From Business Product through Capabilities to API bundles
- Where is the AI?
- Experimentation and Liability
- Findability ends when I have found the product that fits my needs
- 'Support and Troubleshooting In Developer Portals' article
What is the Developer Portal Awards?
The DevPortal Awards is an annual, publicly accessible UX-focused benchmarking study with opt-in participation.
It highlights the importance of strong documentation, clear information architecture, user experience design, and accessibility. It also serves as a space to recognize and celebrate innovative ideas. In our experience, many of these successful innovations soon become best practices.
In 2023, fifty-seven developer portal teams submitted nominations. We saw an impressive dedication to onboarding experiences and setting a new standard for “time-to-wow”. It was also evident that significant effort is being invested in technical writing and community engagement.
In 2024, forty-two developer portal teams stepped forward to join the DevPortal Awards, including renowned global brands and promising SMEs.
Each year, we host and support a panel of independent jurors within a process that ensures confidentiality and impartiality. They are volunteers with extensive knowledge of API programs, developer portals, and API documentation. The suggestions and highlights going forward are an amalgam of the awards learnings and some of our own.
Discoverability and Findability
The concepts of discoverability and findability are both essential in developer portal design, but they address different aspects of user interaction.
Today’s developer portal visitors expect a clean, accessible, and multimodal experience: one that delivers information instantly, in ways suited to different preferences for consuming content. Clear information architecture and smooth onboarding are now just the baseline for a satisfactory user experience.
While many portals offer useful information, few make everything easily accessible from the main landing page. The challenge lies in presenting the offerings clearly, while still enabling users to explore API libraries, use cases, pricing, compliance, testimonials, and technical documentation. But with so much content, it is easy to create noise, making it harder for users to find the product that truly fits their needs.
The goal is to provide all the details without compromising ease of navigation. We need to support both deeply technical users and those focused on business use cases.
What is the key difference between finding or discovering an API?
Findability refers to how easily users can locate something when they are actively searching for it. It focuses on the ease of access and searchability of information. If something is "findable," it means that it can be found through clear, effective search mechanisms, navigation, or an index.
A well-organized site with an intuitive search function and a structured sitemap enhances the findability of content.
Discoverability, on the other hand, is about how easily users can encounter content or features that they weren’t necessarily looking for, but which may still be relevant or useful.
It's about facilitating serendipitous discovery in a non-intrusive way: helping users come across new things they might not have thought to search for, but that can still add value.
With the principle of "every page is page one" in mind, the portal must support both discovery and search journeys. It has to highlight valuable content while allowing users to switch seamlessly between modes at any time, often without even realizing it. This is clear in theory, but easy to lose sight of amid day-to-day content creation.
Common search experience antipatterns
When it comes to search functionality on developer portals, several recurring antipatterns can hinder user experience.
Some portals offer no search at all, forcing users to navigate manually through extensive content. Others restrict search behind authentication, which limits exploration. At the very least, a public overview should be available.
In some cases, albeit the search function exists, it yields irrelevant results or an overwhelming amount of information. There might be an AI-driven search, but if it fails to deliver meaningful answers, it only adds to user frustration. Basic search functions often struggle with similar words or synonyms, making it harder for users to find what they need unless they know the exact phrasing.
Language can also be a barrier. Content that leans too heavily on internal jargon without explanation, or offers no guidance on domain-specific terms and concepts, puts unnecessary strain on users. Even when information is easy to locate, it is sometimes incomplete, leaving the search effort ultimately unhelpful.
Four ways to improve findability and discoverability on your developer portal
Distilled into four actionable pathways, the jury panel recommends the following:
First, include the “why” behind the product on the same page as the technical information. This helps users quickly understand the value proposition and assess whether the product fits their needs, ultimately leading to faster and more confident decision-making.
Second, recognize that simplicity improves findability. Many portals suffer from complex user flows and cluttered interfaces, which make it harder for users to locate key resources. Streamlining the experience enhances clarity and reduces friction.
Third, for portals with large volumes of content, it is essential to deliver highly relevant search results. Without this, users are more likely to abandon search in favor of manual navigation or leave altogether.
And fourth, introduce distinctive, user-centered features in your API catalog. Take the time to obsessively research what would truly serve your specific audiences, and tailor your design choices accordingly.
Examples for your inspiration
All developer portal screenshots are taken at the of October-November 2024, as illustrations.
The following portals were all praised by the jury (some as winners) for their specific ways in which they enable better findability and discoverability practices for their users.
If, while comparing these outstanding examples to your own developer portal, you feel you fall short: remember that all award-winning portals are the result of significant investment in time, budget, expertise, and sustained focus. They are the outcome of many iterations. There is no perfect general solution, only brilliant solutions tailored to specific contexts and constraints.
The examples highlighted in this article will focus heavily on effective ways of exposing use cases, as we believe this is where the most significant progress is currently being made.
The FactSet developer portal won the Best Findability of Products in a DevPortal award in 2023.
The portal provides a comprehensive experience to discover and find the right product.
As the jurors emphasized, there is no one golden pathway: users should have the option of multiple navigation paths to find the right outcome. It is great how the connected recipes are called out, we are seeing this more and more often.
The portal does very well in connecting solution pages to specific APIs and recipes, along with calling out trending APIs, and having a strong product catalog with filtering and searching.
As their Digital Infrastructure & API Product Manager said, they 'developed the idea of showcasing the APIs and the context of large solutions, and workflows, making it easy for users to navigate and discover the right product’.
The jurors liked the Mercedes-Benz developer portal for how they tell the story of why these APIs are relevant, they engage people.
One of the hardest things to do is to motivate an engineer with marketing storytelling, and here you are motivated to start playing with the APIs.
The portal has been spotlighted several times over the years, also as an example for being on brand on knowing your audience well.
The jurors gave very similar feedback about the Viam developer portal last year: that it does an amazing job of motivating and engaging developers. Of course you could say, 'Sure, easy to do with cars or robots...' - but it is a skill too, to know your strong points and play on them.
Status and incident history is information one would definitely want to see.
The system status page on the Mercedes-Benz data products is a sleek overview table, and the history is explorable below.
The Shell developer portal is another example for an elegant status page.
Notice the option to specifically search for the one you are looking for, to filter for past and present, and there is of course a general overview.
The US Bank devportal does an excellent job of creating an experience around their products.
They ensure that the products are readily accessible throughout the entire journey. This is one of the award winning portals.
The jury was particularly impressed with the detailed descriptions for each product, which clearly articulates the use cases and answers the question, ‘Why would I use this product?’.
Additionally, the search functionality stood out, featuring advanced filtering options and relevant results that further enhanced findability.
The award-winning Worldpay developer portal is also an inspiration.
They have developed a simple yet effective experience that clearly highlights their products and catalog. Their thoughtful use of filters ensures that users from around the globe can find solutions that work for them.
The jury was extremely impressed that they not only provided an excellent catalog experience but also demonstrated innovation with their Solution Finder feature, which helps users from diverse audiences find the solution that best meets their use cases.
The Payments Hub developer portal
The excellent and inspiring portal does a great job of guiding the users to finding the product that fits their constraints, while keeping them in the overview as well.
This page from the Pandadoc developer portal is an example of how much you can achieve with some attention and forethought.
It says: ‘Here's a breakdown of the embedding use cases so you can choose the one that suits your needs.’ Simple, effective, no fluff.
Going against the general spirit, but not all solutions comparisons have to be AI-powered. Let's say it is complementary, and some people do love tables. Such simple overviews can go a long way instead of nothing at all, or something that is hallucinating all over your docs.
A small but important nuance can be seen at the bottom of the screenshot: One, is the clear indication how long ago this page was updated. With that information, we could argue back and forth. It is neither here nor there because it could have been a typo that changed, or a new product was added to the table, we do not know. So ultimately it is for sheer transparency but your dedication to transparency works towards users trusting your docs and the product.
If you go further, another example of helping users with the cognitive load and truly understanding the use case: a workflow diagram. While tables may not appeal to everyone, many of us appreciate flow diagrams: it makes complex processes easier to grasp.
When the visitor is not so technically inclined, use cases are especially helpful.
At a minimum when you land on an entry point, you should see 'What we do, what we offer to solve this problem,' even if the explanation is not packaged as a use case, but as intro content, or wayfinding, and so on. Show how you as the provider solve these problems using these APIs.
Explain what you do around here
If the portal visitor does not actually know the company, a basic API catalog can get very confusing. Inform the user in a few sentences on what the company does without marketing-heavy texts. You have to help them find the solution to their problem, with or without industry knowledge.
The UPS developer portal also uses multimedia.
It gives a video of their customers, showing how the customer is using UPS' API internally to make an assessment on delivery or not. As a testimonial, this was an eye-popping experience, it is not just a case study but a true testament to solve an exact use case. It helps to understand their customer segment, the API portfolio, and how they solve the customers' problems.
The Postcoder API docs site is also an award winner in 2024.
The site covers easily understandable use-cases. What is laudable here is that the copy does not assume the audience is already familiar with the domain. Instead, it connects the topic to everyday experiences and offers a clear, well-crafted explanation. From page one, through all pages, we are informed what Postcoder is.
Jurors called out the concise descriptions, focus on use cases, quickstart guides and pricing details which made their offering easy to understand and assess as a prospective user.
From Business Product through Capabilities to API bundles
When the awards jury evaluated portals nominated in the Best Served API Business Model category in 2024, one theme stood out:
Empathy for the user’s journey is essential. The jury favored portals that clearly guided users from a product overview through to examples of real-world business problems the product solves, and into workflows that connect solutions to APIs. The ideal experience enables users to easily locate relevant APIs, quickly run a successful test call, and confidently assess whether the offering meets their needs.
The jury also noted that supporting elements like release notes, status pages, changelogs, and visible timestamps for the latest updates all signal that a product is actively maintained and trustworthy.
However, large-scale platforms face a distinct challenge: the sheer scale and complexity of their offerings. It becomes increasingly difficult to demonstrate how multiple APIs work together to support various use cases.
Meeting this challenge requires a sophisticated translation layer between business products and their associated APIs. Some portals manage this complexity more effectively than others by offering clearer connections between products, their capabilities, and the problems they help solve.
The Sabre developer portal is a stellar example of how a very complex space can be made discoverable.
Users can find what they need and assess whether it fits the constraints of their use case, and also the overall experience feels impressive.
It reflects a high-level of product leadership, thoughtful UX research and design, and excellent documentation work.
The workflow for car reservations, explained in the guides, spelling out clearly in two different ways to connect the relevant APIs. It also highlights the alternative options.
Where is the AI?
Why are we not showing wonderful examples of AI-augmented devportals?
One reason is that all the exemplary portals mentioned above already have a head start when it comes to leveraging generative AI. They have carefully thought through their offerings and dependencies, have professionally written and maintained documentation to build on, and they know who their users are and what they need.
Although we introduced a new category, AI-Augmented User Experiences on Developer Portals, in 2024, we received very few nominations. In the bracingly honest words of one juror:
“I get excited when I see AI-augmented search on sites, and my initial thoughts go like, ‘Wow, they must have a lot of faith in their documentation!’”
Because the catch with large language models is this: the quality of the output depends directly on the quality of the input.
At present, there are only a few examples of AI-powered product or solution finders that work well in the wild. A common frustration for users is also the lack of clear privacy communication: policies are often absent, vague, or buried under blanket corporate statements.
AI, APIs, Documentation & Developer Portals: learn with us at AI The Docs! Fully virtual conference, 24-25 June.
Experimentation and Liability
Early, overhyped expectations predicted a near future where intelligent chatbots would seamlessly answer all your interface-related questions. In reality, deploying autonomous AI agents on commercial sites is a complex use case with equally complex solutions; and if poorly executed, it can become a serious business liability. While there is a lot of experimentation happening, very little has been deployed publicly so far.
We believe the low number of nominations in the AI-augmented documentation category reflects this reality: most projects are still internal and experimental. Especially in large organizations with fragmented documentation silos, AI-augmented solutions are typically used internally as confidential RAG (Retrieval-Augmented Generation) tools, not for external-facing content. And that is far preferable to irresponsibly hallucinating in front of your users.
Keeping this note of caution in mind, we recommend exploring what is viable within your own context and constraints, and then iterating. Use generative AI to improve content discovery, enable smoother workflows, and help users uncover new possibilities.
For this, you will probably have to apply
- Cognitive Search: The search system uses natural language processing to understand developer intent and provide recommendations beyond just keyword matching. For instance, if a developer types "recommendation system," the AI could suggest related APIs for recommendation engines and machine learning, alongside articles and tutorials on building such systems
- Content Personalization: Dynamically adapting content based on user behavior or past interactions. While not a new concept, generative AI significantly expands what is possible in this space.
- Predictive Suggestions and Support: Using machine learning to anticipate which tools, services, or integrations might be useful next. This allows you to guide developers more effectively and introduce them to new features in a timely, contextual way.
All this hinges on accurate and up-to-date documentation that is well-structured, consistent, and modular. These systems only perform well when built on rich metadata and a robust tagging structure.
We also recommend incorporating feedback loops and mechanisms for continuous learning to keep the system evolving.
Notes of caution
We’d like to offer two gentle but important notes of caution.
First, tracking user behavior comes with legal and ethical responsibilities that cannot be ignored.
Second, a nuance well-known among documentarians: traditional marketing metrics do not directly apply to documentation. Did someone bounce in 10 seconds because the content is not what they needed, or because they found exactly what they needed and moved on, satisfied? Technical documentation is not long-form marketing, and user behavior must be interpreted differently.
If you’re wondering whether you should write differently for large language models than for human readers, the answer is no. But you should absolutely structure your content with intent: semantics are the new black.
For practical guidance on what, why, and how to optimize your technical documentation for LLM consumption, we recommend reading the latest articles from our technical writing team on AI-readiness.
What is AI-ready, structured content on your developer portal? Explore the importance of a solid content strategy.
We outline five practical steps, from prioritization to metadata strengthening, to help make your content AI-ready.
Findability ends when I have found the product that fits my needs
To close, let me emphasize an often-overlooked truth, best captured in the words of one of our jurors:
"Findability ends with finding the product that fits my needs. Not just A product."
And one more practical reminder: give your APIs clear, meaningful, and distinct names and descriptions. Many users will fall back on Ctrl-F, and it only works if your content is readable and specific.
The 2025 DevPortal Awards nominations are open until mid-summer. Visit devportalawards.org to submit a portal or browse the nominees, including those featured in this article and many more.
If you would like to stay informed about our research and insights on developer portals and enterprise API documentation, subscribe to Pronovix’s bi-weekly newsletter.
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.
