How can you reduce the onboarding friction and build more trust in your APIs? How can you serve both engineering and business line inquiries into your large API portfolio?
Developer portals have evolved beyond API repositories into multifaceted platforms with a diverse user base. To address the plethora of different backgrounds and needs, portals are now home to features and content that allow access to the API ecosystem for non-technical users, as well. With the emergence of business-initiated inquiries, portal teams need to make sure that in addition to supporting developers, they also facilitate informed decision-making for business users by enhancing the discoverability of their API affordances.
In this article, we’re highlighting some of the processes and insights shared at the Showcase Your Developer Portal Series by Deutsche Börse Group, UP42, Codat, Cloudinary, NewDay, Nexio, and Masdr.
Serving a wide range of personas
Developer portals can be so much more than just a collection of APIs and documentation. Mature portals offer features that reduce the onboarding friction and make the integration process as seamless as possible. However, as developer portals grow in scope, they need to accommodate more and more different user personas with unique needs and backgrounds.
Deutsche Börse Group’s API platform provides solutions for both publishers and consumers. The platform supports API publishers with a self-developed API gateway, documentation, visibility options, and analytics. On the other hand, API consumers can benefit from API searchability, an API catalog, and subscriptions among other helpful features.
UP42’s documentation hub supports users at every step of the customer journey, and helps them make an informed decision about how they engage with the product offerings. To make their product portfolio easier to navigate, UP42 offers step-by-step tutorials to those who require more guidance, while their API reference page is aimed at more experienced users. UP42’s user-friendly console is the first point of contact for business decision makers, and its content is tailored to this audience, although it does require registration. The console offers a general overview of functionalities to help business users understand how UP42’s products can support their goals.
Codat’s documentation portal also offers different types of users a comprehensive understanding of their product offerings. On the portal, products are broken down by use case. This way, business users with a specific problem in mind can get a clear view of Codat’s solutions. The portal team also crafted a developer journey that can be tailored to individual preferences. Developers can choose their own path based on how familiar they are with the products: they can get a thorough introduction if necessary, but they can also get started with the integration right away.
How can you enhance your developer portal by empowering developers with guides that meet their expectations?
Content curation is essential
With carefully curated content, you can render complex concepts more approachable, lower the barrier of entry, and keep visitors on the fastest track to decide and engage.
To serve every segment of their audience, NewDay crafted separate user journeys for different sectors, and also considered the needs of non-technical users. In order to help these users navigate their developer portal, NewDay utilizes content in a way that facilitates a thorough understanding with guides and demos that bring APIs to life. As Megan Jackson (Product Analyst at NewDay) observed, ‘our portal is only as good as its content’ – further emphasizing that content for guidance and explanation is not an afterthought but an essential layer for a successful developer portal.
For a better developer experience, Cloudinary has a dedicated API & DevX (Developer Experience) writer team: on top of writing documentation, they also create video tutorials, demo apps and code sandboxes to add interactivity to the portal. In addition to enriching the portal experience, the team is also very active in the API community. They contribute to developer blogs and create video tutorials outside of the portal, and they also participate in various conferences and training programs.
As developers come from different linguistic backgrounds, the way written content is presented can either add further cognitive barriers, or enable a seamless flow of information and level the playing field. Carefully consider your portal's vocabulary and style, this is essential for inclusive and effective collaboration with your users.
Communicating intricate ideas of a specific industry can be a challenge even without a language barrier. UP42 uses simple and clear language in their content to ensure that their message is accessible for a wide range of users – many of whom are non-native English speakers. The principles of Global English aim to establish a common ground for communication to bridge the gap between native and non-native speakers. For cases where the use of technical jargon is inevitable, UP42 is developing the reference section of their documentation which provides textbook descriptions about the products, so users with less experience can get a quick overview and make an informed decision about the product that best suits their use case. Their pointers to choose API offerings from the glossary are particularly interesting.
Comprehensive support solutions
With a large and diverse range of products, it’s paramount to provide support throughout the integration process. This support, of course, needs a lot of capacity from the maintainers of the portals, which is often not budgeted for or not enough time and expertise is readily available. How do teams achieve excellent API integration support? Let's see some real life examples.
Deutsche Börse Group’s platform consolidates a large number of services from their entire value chain, so it’s important for them to provide technical support on top of the detailed documentation. Technical support requests are mostly handled by their own team, and they also created a dedicated mailbox which connects specific questions and suggestions with the appropriate API publisher.
Some developer portals utilize AI solutions to enhance their support efforts. This is a growing, albeit very costly trend that most docs teams have in their sights by now.
What steps can organizations take to ensure that they can use AI safely and effectively in the future?
Nexio has implemented an AI chatbot as a direct point of contact for decision makers that serves them the information they’re looking for. While conversational AI certainly accelerates the access to information, Nexio also has an integration support team that oversees and guides the entire integration process.
Codat also harnesses the benefits of conversational AI. Powered by GPT-4 and trained on Codat’s own data, Cochat is a proprietary tool that helps users navigate a wide range of solutions. Cochat combines Codat’s knowledge base with general best practices to serve users comprehensive and helpful responses that otherwise would require several different sources.
What does the future hold for the intersection of documentation and AI? At the AI The Docs conference, we'll explore emerging trends that shape the AI landscape.
Evolving business priorities and continuous improvement
Deutsche Börse Group’s API platform started out as an IT upskilling project, initially targeting developers. Their primary focus was to serve the developer ecosystem, including publishers and consumers of APIs. As new demands emerged, the platform also had to evolve. The real turning point happened when the team started focusing on business users who have different needs and expectations compared to software developers. As business roles are often tasked with allocating resources, their support is instrumental in further developing the portal.
In order to better align with business needs, the team decided to focus on improving their API catalog and searchability, and they’re also working on analytical dashboards and monetization solutions that directly address business goals. This mindset is also reflected in how they refer to their portal: instead of calling it a developer portal, which might alienate their non-technical users, they call it an ‘API portal’.
Nexio’s portal team relies on metrics to provide feedback and validation for their efforts. Based on data about the way people use the developer portal and the different sources of traffic, an AI tool looks for patterns and highlights areas for improvement. This focus on constant improvements ensures that the portal continues to serve evolving expectations from both business and technical users.
Showing extraordinary dedication to developer experience, Cloudinary has appointed a VP of Developer Experience and Self-Serve to represent these areas on the board and harmonize efforts throughout the entire company to better serve developers across the different teams.
NewDay created internal feedback loops to gather information about their internal developer portal's performance, and they use these insights to improve their external portal as well. The team organizes show-and-tell sessions, where prototypes and designs are presented to internal software developers to capture their first impressions. They also maintain an open-door policy which encourages honesty and transparency, and they urge team members to share their experiences with their internal APIs. The feedback loop’s goal is to gather candid information as early as possible, so the team can improve both their internal and external developer portals.
Bespoke business models and monetization
Working as a service provider to banks often requires unique solutions to address the relevant regulations and specific business needs of each client. Deutsche Börse Group’s client base consists mainly of banks, however, exposing certain services through APIs has attracted new clients from unexpected sectors, such as insurance companies who had an interest in the data on the platform.
The portal generates value by consolidating the services offered by all the different companies in Deutsche Börse Group’s value chain, so customers can enjoy the benefits of a one-stop shop for all the data they can gain access to. Only one login is needed to access the services on the platform, and some of them are even free of charge. Building on the success of the portal, the team is planning to expand the range of services on offer and also introduce new APIs that can be monetized.
As for monetization, Masdr has two package options based on company size: one for large enterprises and another one for SMEs. Large enterprises can choose to follow a “per hit” monetization model where charges are based on individual interactions or a bracket system that sorts annual usage into tiers. With the bracket system, increasing discounts are applied as usage reaches a higher tier. This encourages companies to use the service more.
Over the years, developer portals have had to adapt to the changing business needs: they have to cater to developers while providing valuable insights for decision-makers at the same time. As the exemplary portal teams above highlighted, it is more than possible to serve each type of user without sacrificing the quality of service provided to the other.
As technology and user expectations continue to evolve at a rapid pace, it is more important than ever to bridge the gap between technical considerations and business objectives. Business users benefit from concise and informative content that ensures confidence in the decision making process, as well as comprehensive support solutions and a transparent pricing model. By considering the requirements of decision-makers, developer portals offer a cohesive experience that caters to the concerns of various user groups.
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.