What can be the pitfalls of a preset, out-of-the-box developer portal framework? How can AI help you to improve developer experience? How can you build confidence and enable self-service with onboarding? We had a chance to peek behind the curtains of some DevPortal Awards nominees’ portals. This article focuses on developer experience, which also encompasses onboarding, and highlights some of the best practices we saw from the nominees.
Table of contents
- Limitations of out-of-the-box and SaaS developer portal products
- Developer experience best practices: flexibility, findability, and transparency
- Developer experience best practices: onboarding as the first point of contact towards your API offerings
- Developer experience best practices: gamification and AI
- Closing thoughts
- List of the Showcase Your Developer Portal presentations (first and second sessions)
- Accessible Features and Tools for Developer Portals - API The Docs 2023: Lessons learnt from Showcase Your Developer Portal Conference Series, Part 2
- Further Resources
Limitations of out-of-the-box and SaaS developer portal products
An out-of-the-box developer portal can speed up your go-to-market. But after a quick launch, a developer portal that cannot be customized can become a roadblock to the long-term success of your API program. As the API portfolio grows and matures, your strategy will probably change and require more specific business experiences. In this case, a preset solution may no longer suit all the desired goals, and retooling might become necessary.
The Codat Docs team went through such a journey: they wanted to have more flexibility and control over their docs, and they built their own custom solution. Now, their documentation site is more resilient. With the help of the new landscape, large-scale changes can be managed on over three hundred pages of content without interrupting the existing user experience.
To mention another example, the Monite API Developer Portal uses a robust content management system that is exclusively tailored for developer documentation. The comprehensive resource was designed to provide an end-to-end self-service experience to developers.
The ability to extend and customize your developer portal plays a crucial role in executing on the API business strategy.
Developer experience best practices: flexibility, findability, and transparency
Understand your audience
Information architecture is the practice of planning and organizing content on your developer portal into a structure that your audience can explore and digest. Before the actual building of a developer portal, one has to know who will be the portal’s audience. Keeping that in mind, Mercedes-Benz / developers made the product overview page so that it can be filtered by use case (the offered tags behave as an indicator of who are the portal’s users).
Another method to better understand the audience is to communicate with the users. Developer Hub Novopayment does user research, so they can gain feedback directly from internal and external audiences. To guarantee a better experience, they rely on analytics, interviews, and A/B testing.
In the case of Cloudinary Docs, the homepage was especially designed to target and serve the developer audience as this is the page that helps users to understand where they can get started. On Cloudinary’s homepage, the first two main sections encourage exploration, while the ‘Top SDKs and libraries’ section showcases the logos of the different technologies, which can be easily recognized by developers. This works as an indicator that the company supports their preferred language.
API explorers and API guidelines
Using an API Explorer is a common method to make the products searchable. Monite designed all of their content to fit the API explorer (e.g., descriptions with cross-linking between the guides and the API reference).
Open-source SDKs and API Guidelines help to easily access the code and learn how the standards of a given API works. If users can register and obtain keys at any time with ease, friction can be reduced. These are the principles that the Monite API Developer Portal follows. They also provide video tutorials, sandbox environments and forums.
The Payments Hub Developer Portal’s team deployed self-service sandbox credentials for select products, and provided the ability to download SDKs and code samples, so developers can easily get started.
Transparency
Having a transparent workflow and content makes the users’ interaction with the developer portal more seamless. For example, a dedicated technical content team can contribute to a better developer experience. In the case of Codat Docs, this team maintains the documentation, produces public-facing content, creates Open API Specification (OAS) files, and generates client libraries.
How can the manual creation of Open API Specification files help to improve developer experience? The rich and detailed OAS is accessible for technical writers and other collaborators to contribute. Codat achieved more control over the OAS in order to group, tag or hide endpoints, and it is easier to contribute without being familiar with the code repository.
To make the users’ work seamless, the Miro Developer Platform uses an embedded code editor. This way, developers can try the web SDK directly from the developer portal. It means a fully integrated experience, and users can learn and practice right from within the documentation itself. As Miro observed, if one consolidates all the information developers are looking for, it will require less time to search for guidance.
Transparency is also an essential aspect of developer experience. Codat’s navigation offers a clear path to the users. One can learn how to configure the solutions, and then move on to using the API. It’s also possible to immediately dive into specific products.
Developer experience best practices: onboarding as the first point of contact towards your API offerings
Onboarding serves different purposes: evaluation, education, and acceleration, and plays a crucial role in its function as the first step of user experience. Giving too much information can be confusing and overwhelming, while providing only a few details leaves the user in confusion.
To provide a convenient onboarding journey, the Payments Hub Developer Portal focused on the target audience’s needs. They realized that developers may not be familiar with payments, and some users are not software vendors. To offer suitable onboarding, they planned with the possible user personas. For this reason, Payments Hub created an easy-to-register process, so users do not have to provide too many details.
In Miro Developer Platform’s case, developers start on the ‘Guided Onboarding’ page, which consists of a list of topics that take them through a guided path (called ‘Onboarding essentials’). Here they can discover, learn and test on the go. To make the learning experience more effective, the page also offers practical tasks. The progress bar indicates how much the user has done, and how much is left to complete the onboarding flow, which is crucial from the point of expectation management.
How can one make onboarding better? The already mentioned step-by-step guides, and a sandbox environment can be some of the many tools that make the journey better. Mapbox offers many ways to support their users: they provide tutorials, how-to videos, troubleshooting guides, glossaries, and so on. To mention another example, Mercedes-Benz / developers also use step-by-step guides, but also have a support area on their portal which includes an FAQ section.
On the Developer Hub Novopayment’s website, there is a simplified starting point, to make it easier to find everything. According to them, one of the best approaches is to explore the content and the APIs' capabilities, before committing to using one of them. Novopayment also offers real-time online registration and projects, and a sandbox environment.
As we learned from Cloudinary Docs, ‘onboarding is an ongoing process’: there is always room for improvement and opportunities to help users to grow.
Developer experience best practices: gamification and AI
The Miro Developer Platform came up with a gamified experience to make onboarding an entertaining experience in the form of collecting badges. Having collectables can encourage learning. Miro offers interactivity of the learning process in the form of a challenge. In the ‘Where’s Miro?’ challenge, users use the Miro web SDK to uncover hidden secrets. This way, developers can test and practice the necessary skills needed to become an experienced Miro app developer.
There are many other ways to gamify the user experience. Mapbox Docs built a Developer Cheat Sheet which is a compact user interface, smaller than the developer portal. If one hovers over the cards, a few explanatory words show up. This is a fun way to clarify what the different services and APIs do. Clicking on a tile leads to the actual API documentation. Besides the API documentation, Mapbox also has a feature called API Playground. The playground is a user interface that is built around crafting API calls.
Humanized communication and assistance with the help of generative AI
AI is a topic we cannot avoid in the context of developer portals. If we look behind the curtains, exceed the hype, and try to think about its everyday use, one question emerges: how can we safely and effectively use the possibilities it offers?
Users sometimes encounter complex problems that we cannot foresee. For this reason, Codat created Cochat: a conversational tool powered by GPT-4. Cochat was built in-house and trained on Codat’s content. Large language models are suitable for documentation because they can pull together disparate content, summarize it, and highlight the main points. Even though the documentation on Codat’s site is maintained in English, Cochat can understand any language, and pull the necessary information.
Monite also relies on AI-based search on their developer portal to provide humanized communication and assistance. Relying on the prompts, AI provides the answers and shows the right pages. Monite’s search engine has learned inside its documentation, and it does not have character limitations.
Closing thoughts
There are many ways to improve the developer experience and provide a frictionless user journey. From a well-defined onboarding process to transparent guides, findability and the usage of AI, there are countless solutions. This article highlighted some of them, based on the DevPortal Awards nominees’ presentations.
One of the key elements is to understand the target audience: this way, the developer portal can be used to cater to the users’ needs. It can be a challenging task, but it is worth planning with this aspect.
The other crucial aspect is to remain flexible as, in this fast evolving industry, the business strategy needs to be up-to-date. Customized features are a way to keep up with the trends. Thanks to the DevPortal Awards nominees, these trends can be easily defined. With their help, the path forward is clear: use the best solutions available today and push the boundaries of what we believe to be the key components of a developer portal for tomorrow.
Are you building a developer portal? Do you need help? Talk with us to learn how our Zero Gravity developer portal can accelerate and simplify your launch or help on your journey.
Read More about our Devportal Solutions »
List of the Showcase Your Developer Portal presentations (first and second sessions)
4 October: DX Innovation
- Paulo Victor (Lead Technical Writer): Monite API Developer Portal
- Polina Zaichkina (Senior Technical Writer), Max Clayton Clowes (Product Director): Codat Docs
- Mira Balani (Staff Technical Writer), Anthony Roux (Head of Developer Relations): Miro Developer Platform
11 October: Onboarding
- Laura Olson (Product Engineer), Bryan Long (Director of Product Management): Payments Hub Developer Portal
- Jackie Rosenzveig (Sr Dr of Documentation and Doc Experience): Cloudinary Docs
- Sebastian Gomez Merizalde (Product Owner): Developer Hub Novopayment
- Chris Whong (Senior Developer Evangelist): Mapbox Docs
- Valerie Uhl (Product Owner): Mercedes-Benz / developers
Further Resources
- Onboarding As a Key Aspect of Business Success
- Developer Portals as Digital Marketing Tools and Technology Choices for Devportals
- Expectation Management For API Products - Setting Yourself Up For (developer) Success
- Building Developer Portals Step-by-Step: Information Architecture Workshops
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.
