Skip to main content
Content Editor & Writer
Nov 10, 2023

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

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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 »

 

Contact us »

 

List of the Showcase Your Developer Portal presentations (first and second sessions)

 

4 October: DX Innovation

11 October: Onboarding

Further Resources

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.

Klaudia is a Digital Content Writer and Editor for Pronovix' Marketing and Content Strategy Team. She conducts research into developer portals and developer experience and writes articles on products, services, and events. She also works on case studies. In addition. she edits the podcast episodes. Klaudia is also working towards a PhD in literary studies focused on video games. In her free time, she practices photography and reads.

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe