The DevPortal Awards seeks the most impressive solutions with the help of independent jurors who are volunteers with extensive knowledge of API programs, developer portals, and API documentation. In 2023, we worked with 13 extraordinary people in the jury panel, who put their hearts and souls into the evaluation. This article highlights some of their remarks which can be guidance for those who want to bring their developer portals and API programs to the next level.
Table of Contents:
- What is more in focus lately?
- What should I change on my developer portal?
- What are the novelties and how do jury members see the future of API documentation portals?
- What does it take to be accessible?
- Recordings
- Closing thoughts
- Best Developer Portals 2023
At the two DevPortal Awards Gala events, we had the honor to interview some of the jury members: Anne Gentle (Developer Relations Leader at Cisco DevNet), Bob Watson (Senior Technical Writer), Chris Bush (Lead Developer Educator at MongoDB), Fabrizio Ferri-Benedetti (Principal Technical Writer at Splunk), Koichi Shiroma (Senior Product Development), Kruno Golubić (Technical Writer at Memgraph), Marco Spinello (Senior Technical Writer at sanity.io), Michael Richardson (Advanced Software Engineering Manager at Kroger), Susanna Laurin (Certified Professional in Accessibility Core Competencies, G3ict and IAAP Representative to the EU), Richard Smedley (Principal Technical Writer at Couchbase), and Ryan Clifford (Platform Group Product Manager at Spendesk).
We asked the same questions from most of the jury members, with the exception to Susanna Laurin, whom we specifically asked about digital accessibility. We would like to bring a kaleidoscope of opinions from industry experts with various backgrounds on developer portals in 2023 and in the future.
What is more in focus lately?
Since the first DevPortal Awards, we have observed the many varying best practices companies follow to evolve their developer portals. In the jury panel, some members have been supporting us for many years, and we also welcomed new - but likewise knowledgeable - members. Seeing how they experience the changes in developer portals and API documentation is eye-opening.
Excellent User Experience
Fabrizio Ferri-Benedetti applauds the constant search for more cohesive experiences, to leave behind disconnected reference documentations and guides with a different look and feel. He also highlighted the emerging trends of localization and internationalization. ‘We tend to forget sometimes that users come from many different countries.’
According to Chris Bush, developer portals have been becoming more practical. This transformation includes the getting started experience: onboarding, and how one can work with the company’s offerings. Doing so means deciding what elements to focus on, and what to present to the user to get them onboard. ‘It’s a challenge, but we have seen it work on the sites that were presented to us.’
Koichi Shiroma also agreed that the overall experience is getting better. The onboarding–as the first point of contact towards your API offerings–is an essential part of developer portals. Koichi underlined that onboarding is more well-thought-out, it’s more than documentation and tools. ‘These days much more focus is on context and the education for the developer.’
On developer portals, Anne Gentle sees better infrastructure for trying out APIs and more mature integration into authentication (in some cases, users can use their own account to try things out on the developer portal). Anne observed more push towards ‘let them try out, even if it’s hard on the backend.’
Bob Watson welcomed that many devportals incorporate user experience research and design. He hopes we will see more developer portals where ‘the customer is recognized as a part of the design process.’
As Richard Smedley highlighted–similarly to Fabrizio–the elements were more cohesive in a lot of developer portals. ‘We are all dealing with something where we can never get it perfect, never get it right. It's great to see,' he added, ‘when you can find enough paths through enough uses, and different use cases.’
According to Kruno Golubić, portals seem to be ‘more oriented to allow users to select their preferences and then they just follow you, and offer you the right things at the right time.’
Are you looking for help with a specific UX task? We help you to meet your developer portal users’ needs and improve developer experience. We can also guide you how to increase the portal's value for your users and drive business growth.
Focus on API design
There are other segments where developer portals have evolved a lot throughout the years.
‘We need to funnel developers towards the documentation, the set of documentation, the set of tools that are really relevant to them’ - emphasized Marco Spinello. He added: users want to see results as soon as possible. ‘We need to consider docs as an enabling tool.’ For this reason, they need to be much more focused than they used to be.
The possibility to interact with any kind of API is essential. Providing a mature sandbox environment improves user experience. As Michael Richardson highlighted, ‘the ability to interact with an API of any kind directly in the documentation is so valuable, and really contributes to that learning experience.’
Ryan Clifford highlighted that he sees more focus on API design, and that there is better attention on ‘how I am designing APIs?’ He added, ‘Part of API design is how do I abstract complexity that my users shouldn’t have to think about.’
What should I change on my developer portal?
As Chris sees, ‘the form needs to follow the function’. For this reason, he suggested leaving animated scrolling behind. The ultimate functionality of a docs site is providing information, and animated scrolling is not practical.
According to Fabrizio, it would be beneficial if developer portals explored other API documentation tools, and left behind copying the well-known unicorns. ‘There’s much room for innovation instead of trailing behind the thought leader in the sector.’
Devportals and APIs have become more “mainstream”, and more providers need them. This can lead to using similar tools, relying on the same approach. Ryan would like to see more portals that aim to make their documentation unique, and try not to be a carbon copy. ‘Build features that are meant for your portal, context, business - not just for the sake of having them.’
Richard mentioned the overuse of sign-up, where ‘you suddenly feel like a unit into the sales funnel.’ According to him, the sandbox environment is much more practical.
Connecting to that, Kruno highlighted that if a devportal offers a function, it should work right away. It is problematic when you as a user expect to have a working example and it ends up being broken, because you didn’t do something like creating an account.
As Michael sees, some companies have confusion about their users, and ‘they may end up with salesy material in a developer-focused portal.’ He suggests, ‘Consider your users and the kind of information they are going to need based on their use case.’
Anne encourages everyone to leave behind the stark difference in visual design between the reference information pages and the “how-to” conceptual information pages.
What are the novelties and how do jury members see the future of API documentation portals?
When it comes to novelties, we see varying approaches and solutions. The jury members listed a few of those, and they also looked into their “crystal balls” to try to predict the future.
Interactivity, custom solutions, LLMs, and AI
As Chris mentioned, 'it was great to see specific hands-on things that you could follow that could get you started.' Regarding the future, he highlighted the advent of LLM and AI. As he sees it, these tools could offer new ways to interact with documentation as they can answer questions, making the whole process more dynamic. ‘You never see the people on Star Trek read the documentation.’
For Fabrizio, it was pleasant to see more interactivity on developer portals. As for his vision for the future, he suggested that developing something should be more playful, and should feel like playing with building blocks.
Koichi found it interesting and inspirational that some developer portals have stories about using an API. ‘The approach was so engaging that it really motivated me to try out.’
There are many different use cases, and they should be addressed. As Richard remarked, he would welcome similar interactivity on developer portals as in the case of the Choose-Your-Own-Adventure books.
Marco highlighted that documentation is becoming much more interactive, and it is where the user needs it. Most developers want to stay within the environment, so the docs should be there too. As he sees, AI and LLMs are a way to get to serving documentation this way.
Going forward with future possibilities, Ryan mentioned the ability to customize a use case based on the needs (like a Choose-Your-Own-Adventure book), and ‘how to articulate that use case and how to get up and running in a simple way.’ This would help non-technical persons.
According to Michael, gamification was a nice addition he was not expecting on developer portals. ‘I’m excited to see where it leads over time.’
Connecting to that, Anne mentioned a delightfully gamified award system on one of the nominee portals. Regarding the very near future of devportals, she mentioned ‘if you are going to make a Large Language Model and use your documentation to train it, ‘[it] would be great if you have already run all of that training content through a linter or two.’
As Bob sees, it should be important to get the feedback all the way to writers and developers. In addition, the level of data that one can collect from a devportal is still an untapped goldmine of information. It should be presented in a usable format.
Accessibility wishlist
Regarding the future, Kruno emphasized the possibility of being able to have a conversation with documentation in spoken words. This alternative would give more accessibility to the users.
According to Marco, accessibility should be one of the standard features. ‘We need to take it as part of the product when we start putting the developer portal together.’
Ryan also emphasized accessibility: ‘How can we do some real novel work on accessibility where we think holistically?’ He raised the idea of being able to choose a specific setting–based on the needs–and the whole portal would change accordingly.
What does it take to be accessible?
Accessibility is getting more recognition worldwide. At the Showcase Your Developer Portal conference, we saw many notable solutions, and there is an evolving trend in developer portals striving to be accessible. For this reason, we dedicated a whole segment to the topic and asked Susanna Laurin to share her experience and advice with us.
Susanna saw many different approaches from the nominees, and as she mentioned, some of them had a real commitment to accessibility. ‘I think the driver is: try to make your portal, developer portal or whatever interface you have as good as possible for as many as possible, maximizing the foreseeable use of what you are doing and making it a good design.’
According to Susanna, if someone follows the minimum requirements, the final result won’t be desirable for the audience. The accessibility standards are a tool, but if someone wants to make their interface useful, they need to go beyond the standards.
One of the best practices of accessibility is multimodality. It means that the same information and content is presented in more than one channel, in more than one format. ‘That is, to me, the essence of accessibility.’ People are different and they have varying needs, so multimodality can help everyone find the most fitting source.
As Susanna sees, one of the most common misunderstandings is that accessibility does not align with visually appealing content. She highlighted: if one focuses on only one user group, there is a chance that everything else will be forgotten. ‘Good design is accessible design.’
Susanna emphasized the importance of relying on people who have permanent limitations, as they can provide valuable feedback on accessibility.
Subscribe to the DevPortal Awards Newsletter to get notifications about nomination, voting, gala event details, and DevPortal Awards winners.
Recordings
Jury interview - part 1
Discussion with Chris Bush, Fabrizio Ferri-Benedetti, and Koichi Shiroma.
Jury interview - part 2
Discussion with Ryan Clifford, Marco Spinello, Richard Smedley, and Kruno Golubić.
Jury interview - part 3
Discussion with Susanna Laurin.
Jury interview - part 4
Discussion with Anne Gentle, Bob Watson, and Michael Richardson.
Closing thoughts
As Bob highlighted, choosing the awarded portals from the nominees is getting more difficult. As he sees, ‘these competitions are starting to pay off, they are literally raising the bar on what is expected.’
It was an honor and joy to work with the jury members who also dedicated much time and effort to the evaluations. Their expertise helps the API community to raise the bar for developer portal user experience, highlight new solutions, and celebrate excellence.
We are looking forward to your nominations for the year 2024, it is a delight for all involved to celebrate wonderful teams' hard work. Many jury members agreed that the DevPortal Awards gives an opportunity to look closely at different industries’ developer portals and recognize novel approaches.
Did you miss out on the Gala events? Read our article on Best Developer Portals 2023, and watch the recording.
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.
