How do I ensure my API’s relevance to my business in the long run? Why does user experience matter for developer portals? Who are the stakeholders? Are there best practices for findability of APIs?
We recently collaborated on a webinar with Google Cloud (Apigee) and Pronovix. The result is “5 Best Practices for World Class API Developer Portals: Your playbook for building API developer portals for IT leaders, product owners, and strategists”. Published in April 2021, a recording of the webinar is available on demand with registration.
Some highlights from the webinar and links for further reading:
“Think about your purpose. It is about developer experience and making integrations easy, but you need to think further: how do you ensure the API’s relevance to your business in the long run? The best way to figure this out is to innovate and collaborate with your community on what your business is going to be like. “ - Kristof Van Tomme (CEO and Co-Founder at Pronovix)
How do you ensure an API’s relevance to your business in the long run?
“Companies realize they need to build the speed into their development process. APIs are the way companies can separate the front-end from the back-end of their architecture.” - Raymond Peng (Sr. Advisor on API Strategy & Platforms for Google Cloud)
The value of your digital value chain is created and limited by the ability of software developers to leverage your APIs. Currently IT innovation happens within a shortage of such developers and time.
However, it is dangerous to sharpen everything only towards the needs and preferences of software developers. APIs as building blocks that allow you to build interfaces are just the start. A range of integration tools focusing on non-developers are popping up, for example low code/no code app sheets that API owners can publish on their developer portals.
Think about the potential of the entire ecosystem you are part of, and the business value you are trying to achieve. Just having APIs and the developers who use it is not enough for long term business success. What are you going to achieve with your APIs? What kind of ecosystems are you trying to address?
6 types of Developer Portals: What are the different developer experiences that we are trying to create? In this article we illustrate how developer portals are evolving to grant access to a broader range of specialized knowledge and tools.
Why does user experience matter for developer portals? User Archetypes, Design Principles and the User Journey
“Developer portals need to provide opportunities that are trustworthy. Everything starts with defining your typical user personas: what are their roles, what are their goals on your developer portal and how would they behave there. Each typical user goes through a user journey with several stops. It is important to provide the right documentation and information at each of these stops to get things done. Make sure you set up the right information architecture. Findable, discoverable, useable, searchable, browsable, accessible: enable your users to avoid frustration, this will give a better developer experience. With such an experience, your users will come back, and even advocate for your portal.” - Kathleen De Roo (UX Designer, Information Architect, and Writer at Pronovix)
At Pronovix, we have the typical user journeys, and then we look into the needs of the specific personas. Connect to the value from the end user’s perspective and show its relevance to their business case. Consider the three elements of user experience, as a thinking framework:
User Archetypes: Who are the portal’s users? What tasks are they trying to accomplish? What unspoken concerns might they have?
Information Architecture as the 1st step in your DevPortal journey: It is important to know the audience specific to your company. In the beginning of our work with our clients, if we have access to real users then we can explore with real data. Otherwise we interview the stakeholders for the user archetypes as well, when we start with the information architecture workshop.
Design Principles: What must we strive for on every interaction? What guides every design decision? How can we empatize with the user?
Developer Portal Design: Increasing clarity and trust for a better developer experience. This blogpost summarizes key design principles as introduction to our new series on great developer portal design, where we will explore the role of design in developer portals, focusing on UI design and graphic design aspects that help to create a better developer experience.
__User Journeys:__ Where are the moments of truth? Why would someone trust an organization with all the work and effort they are going to put into the integration to build on top of their API?
How to Improve Developer Adoption and Onboarding: this article outlines how the features of the Zero Gravity developer portals, from Pronovix, contribute to frictionless onboarding and success in developer adoption.
## Who are the stakeholders? Are there best practices for findability?
How can you think about software developers while increasing business value? Who are your stakeholders?
Are you targeting an internal or external ecosystem, or is it a partner system?
Consider the whole organization, not just the API team, but also sales, marketing, devrel, everyone in touch with your API program.
Your API team is a key stakeholder.
The angles of consideration are of business and development, operational maturity, and how the API specs get to the portal. Usability testing is helpful to show where adjustments are needed to benefit the various stakeholders.
Operational Maturity: DevPortal Maturity Model. It is a common mistake to forget about the authoring and editorial experience while focusing on end users. Who is going to create and maintain the various types of content for your developer portal, and what is their experience?
How is the findability of your APIs on the developer portal?
How many APIs do you have? What do you want to list? This already defines a lot of the structure.
A catalogue makes sense if you have a lot of APIs or will have more in the future, and need one central place for internal and external users for finding them. This gets more elaborate with a search function, or an advanced search function with categorization and multifaceted search. It is possible to start with a simple experience and grow the complexity as your content grows. The decision is also informed by what your users want to find and how they search for it, and certainly on your business structure. We have met cases of internal portals where a whole domain model was mapped into the portal and the developer portal became a
domain catalogue as well.
When to use a CMS for your Developer Portal: this article identifies the key reasons why you would choose a static site generator (SSG) or a content management system (CMS) for constructing your devportal.
Are you planning for 1 or many World Class API developer portals for your business? Need help? As a devportal specialist, Pronovix has consulted for and supported large and medium sized enterprise companies looking for developer portals. Talk with us to learn how our Zero Gravity developer portals and developer experience services can accelerate and simplify your launch.
