Developer Portals are designed to meet the needs of your API producing and API consuming developers, product owners, technical writers, and community. A content management system (CMS) is the ideal framework when you desire a developer portal that meets a high level of enterprise- and future- ready digital experiences including low-code and no code solutions.
As a devportal company we’ve been watching and looking for what we can learn from recent trends in digital experience platforms. Drupal is an example of a useful technological stack that can also be the basis for a digital experience platform. We are interested in expanding on what we can offer. That is why we have started to research what differentiates a developer portal from the new and evolving digital experience platforms.
In this article we ask:
- What information will help you outline what content and functionality should be in your portal?
- When should you integrate with 3rd party systems?
- Why is information architecture a vital base for your DevPortal?
Digital experience platforms aim to integrate different aspects of customer interaction and marketing automation to improve business outcomes. Over time, the developer portal can start to become both a vector for developer experience and a vector for digital experience as well.
Developer experience via developer portals continues to be an API / interface story: provide a framework from which to expose interfaces so that people can then build information pipelines and eliminate several communication steps for deep integration with a company’s products or solutions.
The Interface Opportunity – the potential of APIs beyond developers Join this webinar and learn:
how interfaces can create business value for companies adopting APIs, what stages companies usually go through from an API project to a full-fledged Interface program, and how the interface economy will change the role currently played by developer portals.
In his article “how the move from web CMS to DXP is fraying key social contracts” Preston So (senior director of product strategy at Oracle) suggests that “vendors have made grand compromises and set in stone social contracts to ensure the success of everyone who interacts with a CMS, whether a content planner, compliance officer, or executive stakeholder.” In his example, Preston points out how internal users, content (code and no-code) creators and product owners’ needs for unpublished content preview and digital experience management can go overlooked.
One way of avoiding such a pitfall is by understanding the Information Architecture outlining the requirements of the developer portal (or digital platform). Developers and vendors can set expectations to create any type of experience. At the same time, the actual business needs and purpose of the platform or website needs to be vetted and outlined for what should or should not be delivered.
Teams with a strong UX focus, such as at Pronovix, will always start a project with either an Information Architecture (IA) workshop or a shorter User Experience (UX) workshop to align a client’s vision, stakeholder opinions, actual business needs, and system requirements. We occasionally use a further Technical Architecture (TA) workshop to align and integrate with tools used by customers.
In an Information Architecture workshop, the goal is to define the target audience (personas both internal and external) of a developer portal, understand their needs, goals, and how they use the portal while achieving their goals. We collect all existing information, discover and formulate business goals, and analyze target audiences in detail. We adapt our workflow to the customer’s needs — if some materials are already available (e.g. personas) we schedule alignment sessions. At Pronovix, we will provide advice and guidance both on improvements regarding the current devportal and on best practices that align with the customer’s business goals. We help discover the possible user journeys — all to provide a better developer portal engagement and overall user experience. We use this together with the customer to help design the information architecture (sitemap and navigation system) of the new developer portal.
__The results of an IA workshop may not be obvious at first sight of a developer portal.__
The advantages are manifold in
- supporting the function of a developer portal,
- defining long-term requirements, and
- adhering to the right content and placement of that content.
Functionality of developer portals:
- To enable user journeys. The developer portal needs to make sure users can finish tasks as soon as possible, in the best way.
- As documentation databases for all stakeholders. Users can have different preferences/backgrounds/needs, they need dedicated content.
- As trust signals. The developer portal needs to make sure to generate user trust and reliability on services offered.
- As DevRel tools. The developer portal needs to aid and abet users to progress in their goals.
IA workshops define long-term requirements by:
- Gaining a deeper knowledge and understanding of what content you & your audiences need which leads to outlining the best possible solutions for delivering that content.
- Formulating and prioritizing requirements with the target audiences in mind.
- Collecting the outlines about personas, user journeys, and content components that can be consulted any time in the future (e.g. alignment of future developments), and that can be shared among internal teams.
- Functioning as the starting point for UX design, UI design, content creation and development processes.
Get the right content, in their right spot, at the right time:
- Explore audience roles on the portal & the information they expect to be present, and where they want to find it — from beginning till end in the user journeys
__Recognize when a DevPortal should be a DevPortal, and recognize when it can be more.__
We have previously talked about anti-patterns of developer portals including Frankensites and Tyrannical Toolchains. However, there is a good argument to having the flexibility to integrate with 3rd party bidirectional solutions that are powered by a CMS or other engine. For example, the Drupal CMS is an incredibly powerful framework that can handle many additional technological solutions but on occasion the combined complexity of all the requirements can overwhelm the original purpose. For this reason, a customer who is looking to manage complex set of payments, pricing, and invoicing solutions may be better off with a developer portal integrating with an API management solution with good monetization support like Apigee, a separate e-commerce platform, or a 3rd party billing engine, or a combination of all the above. Creating excess functionality within the devportal itself, although technically possible, can bloat and dilute the ability for the developer portal to grow and evolve into the best possible touch point for customers. It also increases implementation risks, maintenance costs, and complicates system upgrades.
A technical workshop or discussion is often necessary to discover hidden complexities and facilitate mutual understanding about the scope of the project. The sessions and discussions help shine a light on the integration of the developer portal with your infrastructure, and the interaction with internal teams and external user-base. We can get a better picture of overall expectations and as a result provide more accurate estimates about timelines and budget.
Start your planning with defining your Information Architecture to set up your roadmap to success. Limiting your Developer Portal to its intended function based on what needs and goals the workshops surfaced ensures an optimal outcome, controls risk, and supports proper governance. For extra functionality, integrate with best of breed third-party systems. Use the information gathered to keep future planning ‘real’ by aligning with user needs in outlining subsequent development initiatives.
Contact us for more information on how an Information Architecture workshop can help you to identify and deliver on your developer portal goals.
Information architecture for developer portals is the practice of deciding how to arrange various devportal parts and elements (such as functional elements, trust signals, support options, decision maker information and API documentation components) to be understandable, discoverable and findable for the main audiences.
Information architecture (IA) forms the base for good user experience (UX). A customized IA structure will prevent users from experiencing friction when they interact with the devportal.
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.
