How can one make their developer portal, API documentation platform tailored to their users’ needs? Why is it beneficial to boost the developers’ flow state?
We previously introduced results from Pronovix's UX Researcher and UX Designer Teams comprehensive series of interviews with software developers. We confirmed our insights towards deliberately designing our developer portals to optimize users' productivity.
This article is a follow-up with practical steps and examples, building on top of part one. To better illustrate our points, we show examples from among the DevPortal Awards nominees of 2023.
You can also listen to the presentation on which this article is based on:
Table of contents:
- UX research with users: method and results
- User-centered design on developer portals
- Build a portal that your users will love
- Summary
- Further readings
- Part 1: Design the platform for flow: it will help your business case
UX Research with users: method and results
In the course of user interviews we conducted with software developers, 9 of 10 developers reported experiencing a flow state when engaged in activities on API portals such as:
- Learning from API documentation
- Experimenting with an API
- Troubleshooting
These insights highlight the fundamental importance of optimizing developers’ performance during their journey when working with APIs. They reveal that by not merely meeting but surpassing the expectations, we not only ensure their satisfaction but also nurture a profound sense of success and achievement, which stems from the remarkable progress achieved during their flow experiences while working with APIs.
User-centered design on developer portals
For developer documentation, consider developers' needs and how they can achieve their goals without friction. In addition to that, there is potential in optimizing their workflow to flow and maximizing the chance that developers will experience this state of mind so that they can achieve their peak performance. How to do that?
- Eliminate disruptions.
- Foster practices that streamline productivity, for example instant feedback and gamification elements.
Let’s see some practical examples of best practices that foster developers’ peak performance in the main activities when working with APIs. We gathered some examples from the DevPortal Awards nominees of 2023 focusing on activities where developers most often experience this state of mind.
1. Learning from API documentation
Based on the research, the learning phase presents a significant opportunity for achieving a state of flow. During this stage, users typically aim to grasp concepts swiftly and retain fundamental knowledge effectively. From a UX standpoint, incorporating interactivity and maintaining consistency can greatly enhance the flow experience for developers as they navigate documentation, tutorials, or guides.
The categorization that we present in this article is a research-based simplification which might serve as an aid to learn about typical patterns observed in the process of API learning.
Illustrated by the Miro Developer Platform, the incorporation of a progress indicator that provides instant feedback can engage users while they navigate through the guides. A progress indicator positioned at the outset of each document offers insight into the time required to complete the guide. Once this section is absorbed, users have the option to mark the guide as completed, fostering success and a sense of accomplishment as they move on to the next section.
Consistency reigns supreme throughout the guides section of the portal, ensuring that every guide page features this progress indicator and corresponding button. This uniformity empowers users with a sense of control, a pivotal component of the flow experience.
Given the unique skill sets among developers and differences in their expertise level, it's imperative to allow flexibility for them to bypass sections of documentation they may find familiar. Inclusive design has become an essential consideration in today's landscape. While many associate it with accessibility features such as color contrast or screen readers, its essence lies in catering to individuals with varied skills and preferences. By offering options, we ensure that developers of diverse backgrounds aren't sidelined by either excess or lack of information, mitigating distractions and fostering a more seamless experience.
Given the unique skill sets among developers and differences in their expertise level, it's imperative to allow flexibility for them to bypass sections of documentation they may find familiar. Inclusive design has become an essential consideration in today's landscape. While many associate it with accessibility features such as color contrast or screen readers, its essence lies in catering to individuals with varied skills and preferences. By offering options, we ensure that developers of diverse backgrounds aren't sidelined by either excess or lack of information, mitigating distractions and fostering a more seamless experience.
Take, for instance, React.dev, where users encounter "deep dive" sections that can be expanded to reveal in-depth details about specific topics. This approach accommodates both seasoned developers, who may possess the expertise to grasp the overall concept at a glance and choose to skip these sections, as well as beginners who benefit from delving into them for a more comprehensive understanding.
Similarly, Cloudinary Docs integrates video tutorials within its documentation portal. Alongside these videos, Cloudinary offers tutorial content, as depicted in the image below. Furthermore, users can navigate with ease by clicking on timestamp buttons to quickly access sections of interest.
Effortless navigation and seamless search functionality play a vital role in facilitating the flow experience. By minimizing the cognitive load associated with these tasks, users can remain focused and immersed in their workflow.
2. Experimenting with APIs
During the try-out phase, users are actively engaged with the code, seeking real-world examples to comprehend the product's functionality and integration possibilities into their projects. Given the breadth of information they need to absorb during this phase, the potential for achieving a state of flow is notably high.
However, navigating through the try-out process can be challenging. To transform this experience into an enjoyable one, why not infuse it with a touch of fun? At React.dev, users are presented with challenges designed to test their skills and understanding of various actions. These challenges prompt users with tasks to solve within the try-out section, fostering an interactive and engaging learning environment.
Towards the conclusion of these sections, users are offered the option to seek hints or access the solution. As mentioned earlier, integrating gamification elements, rewarding users, and ensuring an optimal balance between skill and challenge are essential for fostering a flow experience and transforming the entire journey into an enjoyable journey.
Incorporating AI solutions into the try-out section adds further value, providing users with immediate feedback through a question-answer format. Codat Docs introduces an AI feature called Cochat, enabling users to pose questions or even request sample code to be generated.
When asking a question, users have a clear goal, and by getting answers quickly, they can solve problems more easily, so there is a higher chance for them to get into flow state.
Spotify for Developers decided to include the try-out function right on the homepage. This way, at the beginning of the developer journey, opportunistic learners can jump to the try-out. Also, they provide a real example as the result of the try-out. Users can use their own Spotify account, and as a result of running the code, they get back their top 5 tracks from the last 30 days. This also enables the users to understand the concept right away, and consequently get into flow.
3. Troubleshooting
In the last step, which is the build step, users really want to work effectively without interruptions. In case of troubleshooting, they want to find solutions to their problems. According to research, this step also includes a higher chance for experiencing flow.
Miro Developer Platform provides the fun element of the flow experience, by adding gamification elements to the troubleshooting journey: badges can be earned in a particular step of the integration. This gives the user the immediate reward that they need, so the experience can also be fun and engaging.
On the Mapbox Docs portal, we can see a practice for enabling live communication. Many portals have community interfaces where users can collaborate with each other. The interview participants also highlighted that they seek these opportunities.
In the troubleshooting section, users have clear entry points to this option, as well as the “Ask AI” feature, which is also available.
Engaging in live communication thus can also be an important element of flow.
On the developer portal of ABN AMRO, we can see some examples of use cases for the support options of the portal.
Users need quick and easy support in case of troubleshooting, and making different use cases helps users to navigate on the support page based on their progress in their integration. This is definitely a step which supports users to stay in the state of flow, by providing clear entry points from their point of view.
Build a portal that your users will love
Lastly, it's crucial to emphasize the paramount importance of understanding user needs. While the best practices shared here are valuable, they may not universally apply to every portal. It's essential to thoroughly familiarize yourself with the specific needs and preferences of your users.
- User journey mapping emerges as a valuable tool in comprehending these needs, encompassing both developer and non-technical personas.
- Informed decision-making rooted in data is key. Utilizing methods such as user interviews, usability tests, and analytics empowers you to adopt a data-driven approach.
Undoubtedly, navigating this terrain poses its challenges. At Pronovix, we ardently advocate for the significance of user research and this holistic approach.
Do you already have a mature developer portal, but there is room for improvement? Usability testing can help you prioritize UX improvements on your portal by discovering the main friction points and problem areas users have during a specific journey.
Summary
As a summary, some things to aim for:
- Interactive journeys are tools you can incorporate into your portal, also giving results as soon as possible after a user enters your portal.
- Gamification elements can have a significant role in the FUN aspect of the flow experience.
- Inclusive design is also something to aim for, taking into account the skill set of developers.
- Feedback about the progress, since this gives the users the reassurance that they are on the right track.
Some blockers that are better to avoid:
- Long, complex descriptions.
- Inconsistent user flows and design elements take away user experience control, which is an important part of the flow.
Further readings:
- Part1 article from this series
- Best Developer Portals 2023
- Enhance Discoverability For Business Users - Developer Portal Best Practices
- Developer Experience Best Practices - API The Docs 2023
- How do developers learn about APIs?
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.
