In this article we explain how Information Architecture (IA) Workshops function, why you should start building API programs with a mind to developer/user experience and growth potential, and how you can take steps to actualize progress within your developer portal.
IA Workshops help to focus on the business objectives and to define user needs to provide meaningful content, materials, functionality and logical site navigation. In the context of developer portals, the IA workshop offered by Pronovix:
- brings your developer portal stakeholders together,
- explores your audience,
- outlines your developer portal site architecture/map,
- focuses on your long-term goals to create an extendable, initial first stage MVP,
- helps you efficiently pinpoint the functionality you need for your developer portal,
- increases overall productivity by lessening the time, expense, and iterations required to get to done.
Table of Contents
- Information Architecture as the basis for good user experience
- How to apply the five planes of user experience to your devportal?
- The Pronovix IA Workshop
- Closing thoughts
Information Architecture as the basis for good user experience
Information architecture is the practice of planning and organizing content on your developer portal into a structure that your audience can explore and digest. Insufficient information architecture can decrease trust towards your developer portal, your developer brand, and your integration products. Developer portals as a source of technical reference documentation require several components. Creating a well-structured base can then be iterated upon as API programs evolve.
Good information architecture is not visible, but the lack of it can lead to difficulties. Some examples of how users feel the absence of information architecture:
- The devportal audience is unable to enter a workflow to get to done. The entry point to accessing APIs is unclear, workflows in the portal are not intuitive, and information may be scattered.
- The audience can not find the content that is there. Frustrated users need to click back and forth multiple times before they can figure out how to proceed.
- There are obstacles to accessing APIs quickly. There are high barriers to becoming a registered user trying to access closed information.
- Users need to contact the API provider each time they need help instead of having self-service support available.
- The developer portal lacks elements that help build trust, such as legal documentation, clear pricing or monetization plans, and information on how secure the solutions are.
How to apply the five planes of user experience to your devportal?
User eXperience (UX), in the context of how a user interacts with and experiences your products and developer portal, is a complex phenomenon that consists of multiple components. If we follow Jesse James Garrett’s outline from The elements of user experience, we can describe the creation of UX as a set of decisions on five layers or “planes”.
The five planes of user experience are:
- Strategy: business goals, user needs
- Scope: functional and content requirements
- Structure: interactive design and information architecture—how the features and functions fit together
- Skeleton: wireframes—more abstract structure of the site
- Surface: theme elements—the “look and feel” of the site
Illustration of five planes from strategy to surface (from abstract to concrete). Source: The elements of user experience: the five planes
If we try to define the upper levels first, we may waste time on an option that should not be available as it does not align with the lower levels’ decisions. This “ripple effect” drives a need for iterative evaluation. It is similar when you balance cards into a house: the foundation will predict how stable the upper levels will be. Decisions made on the ground level affect the number of possibilities available to the upper levels.
This house of cards represents the ripple effect of the five planes. If we move one card or we don’t balance the cards, it can fall. Photo by Sigmund on Unsplash
Examples of how the ripple effect can affect the navigation or look and feel of the developer portal:
- If only a small amount of products are available, is a search catalogue necessary?
- If APIs need to be discoverable, what should the categorization be based on?
- If there are many partners that should be categorized and searchable, is it fruitful to have a partners page showing a flat list?
- If there is no social media activity, is it advantageous to place a link on the devportal, which leads to an outdated or almost empty site?
“When the choices we make don’t align with those above and below [planes], projects often derail, deadlines are missed, and costs begin to skyrocket as the development team tries to piece together the components that don’t naturally fit. Even worse, when the site finally does launch, the user will hate it.” - Jesse James Garrett (Author of The elements of user experience: the five planes )
Build decisions on each of these planes with explicit and thoughtful intent to have a near flawless user experience.
To summarize: if someone wants to make a building, they shouldn’t start with painting. First, know what kind of building is required and who will use it. If the floorplan is missing, the building will collapse with time and change necessitating reactive measures. Instead, take the time to design your building from the ground up. Have the flexibility to iterate in an agile manner on a solid foundation.
The Pronovix IA Workshop
The workshop focuses on long-term goals and outlines a phase 1 for delivery of a developer portal.
Will you benefit from a Pronovix information architecture workshop?
- Do you have a large amount of existing and planned content?
- Do your users have specific needs?
- Are you looking for validation on your content and requirements?
- Do you have different and conflicting strategies that need to be validated or aligned?
- Do you have an in-house UX designer who would benefit from 3rd party help to define strategy and scope?
During the workshop, we use the five plane model to focus on strategy, scope, and structure to identify your developer portal’s needs. We start by asking strategy related questions to define your audiences and content requirements, before jumping into the portal’s structure. Every decision affects possible next steps, therefore it is important to ask the following questions right from the beginning:
- What are your business goals?
- Who are you planning the portal for?
- What inspires you, and who are your competitors?
- How do your desired features and functions fit together?
- What kind of content is needed?
- Focus on user experience and specifically developer experience: what will happen, why, and for whom?
Our information architecture workshops take between 3-4 weeks through interactive online sessions. We facilitate discussions between key players discussing and validating strategy and scope of your devportal within the context of your API program. The workshop sessions help to prioritize features and content in a roadmap for the upcoming development iterations of your devportal —reducing rework. Time is saved in the long run.
Defining your audience
As a precursor to the first step in designing for good UX, we define your portal’s user personas: who are the expected users of the portal, how do they behave, and what are their key tasks that the portal supports.
When illustrating a user persona, we focus on business goals that define:
- who are you planning the developer portal for,
- what are your persona’s key goals and behaviours,
- what are their real needs,
- what will be their journey on your developer portal, what path will they take?
During the Information Architecture workshop Pronovix creates proto-personas for each new project. Proto-personas are assumptions regarding the target audience based on the input from your stakeholders and our in-house knowledge.
Proto-personas help align the stakeholders’ views on who is the target audience of the portal and what the portal provides them with. Proto-personas define or re-evaluate assumptions made within the pre-existing scope of the developer portal. Having a better understanding of your audience’s experience helps to define content and functionality.
Closing thoughts
We recommend that you plan your foundation first. Put your developer portal’s user experience to the test with the five planes to establish your strategy, scope, and align with your stakeholders.
Reasons you will benefit from an information architecture workshop:
- Bring all stakeholders to the table to align and collaborate,
- Outline a long term roadmap within the scope of your API program,
- Identify functionality that benefits your devportal that can then be prioritized for iterative development cycles,
- Create a precise site architecture/map illustrating how users navigate your devportal,
- Analysis of the audience (Whom) you need to target for your developer portal/APIs,
- Make sense of complexity in your devportal design,
- A starting or continuation point for your in-house developer or design/UX team or for taking off with our Zero Gravity developer portal.
The bottom line is that you will gain a better understanding of how your developer portal contributes to the overall success of your API program. Further, you can better articulate and prioritize complex needs that come with being a large global or uniquely specialized enterprise business.
From a business standpoint, you will have a better foundation for your devportal to act as a signal loop to provide feedback for improving your API/interface offering and increase your revenue streams. To find out more, contact us.
Grow and Help Grow: Developer Portal Services: Interested in more services that will benefit your situation and how they work? Find out more about the in-house services we use to provide direction to your developer portal roadmap.
Do you need a DevPortal or are you interested in our services? Contact us to find out more! We will work with you to make your goals a reality.
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.
