A Portal as a Product Approach for Internal Developer Portals

Internal developer portals are a critical asset for organizations looking to implement platform engineering, reduce developer cognitive load, meet standards and increase overall efficacy. However, just because you create an internal developer portal does not mean it will be an automatic success. Portals should actually be useful for developers, or else they won’t adopt them. To solve this, we need to focus on product management practices when defining what’s in the portal, and not solely focus on the engineering attributes of the portal.

To create a successful developer portal, organizations must adopt a “portal as a product” approach, incorporating product management principles from ideation to launch, including user research, prioritization and feedback loops. After all, you wouldn’t launch a product without validating the user cases in it.

This article explores how to use a product management approach to set up your internal developer portal and, more importantly, be clear about how the portal can help developers with their daily routines, increasing their productivity as a result.

The Developer Portal as a Developer Enabler

The primary goal of an internal developer portal is to simplify the lives of developers and enable them to focus on their core development work. This includes reducing cognitive load, centralizing and streamlining workflows, and minimizing time spent searching for answers or solutions. In essence, a developer portal should free developers’ time and cognitive resources, allowing them to code instead of getting lost trying to use DevOps infrastructure and tools.

For development leads and executives, the portal serves as a means of setting standards, shortening onboarding and improving overall team efficiency. To achieve benefits for developers or managers, organizations must carefully consider what to prioritize when setting up an internal developer portal. Enter the idea of portal as a product. I’ll unpack this step by step.

Decide How to Roll out the Developer Portal

Be strategic about decisions concerning how to build the developer portal and what developers should use it for. Instead of focusing on individual portal elements (getting bogged down in the details), consider the end-to-end developer experiences you want to offer. It’s not about having a software catalog or a scorecard. It’s about how the portal changes day-to-day developer routines.

As you would when developing a product, start with a minimum viable product (MVP) covering one or two use cases. Once you’ve established the MVP, add new portal functionality phases over time to enrich the portal for developers and managers. Each portal-development phase should involve training, communication and a soft launch to drive adoption. Remember to define success metrics and measure them to track the portal’s impact. So how do you start?

Take the ‘Jobs to Be Done’ Approach

The “jobs to be done” framework is a crucial tool for understanding developers’ needs and the tasks they aim to accomplish using the internal development portal. Instead of making assumptions about what features to add, this framework encourages organizations to identify the specific tasks developers want to achieve, such as deploying a service quickly or managing permissions efficiently.

These example sentences can help you gain a clear understanding of the tasks developers need the portal to support:

• Developers use the portal to get ______________, instead of ___________.
• When _______, developers will go to the portal to see ___________ instead of ________.
• Instead of ______________, developers can check the catalog, and use actions.
• Instead of taking __________ to _____________, developers can ____________.
• Services won’t move to production before ___________ are checked.
• Drive all developers to perform ________ by _________, avoiding _______________.
• Get a full picture of _____________.

Identify How People Want to Use the Portal

Once you complete these sentences, you’ll end up with user stories that you can play out in various use cases that serve developers in their day-to-day work. Here are some high-level use cases that facilitate developers’ daily workflows and tasks:

• Adhere to internal development standards by offering guidelines and best practices.
• Expedite the process of bringing new features to production.
• Facilitate the adoption of Infrastructure as Code (IaC).
• Streamline incident and on-call management.
• Simplify interactions with Kubernetes.
• Manage application security posture.
• Handle feature flags.
• Monitor service health.
• Understand internal APIs.

Development managers and leads can also benefit from an internal developer portal, for example:

• Staying on top of costs: Tracking and optimizing costs at a granular level to improve resource allocation
• Onboarding new developers: Reducing onboarding time by providing a streamlined experience with guardrails
• Driving engineering quality: Initiating and overseeing projects to improve production readiness, code quality and other aspects of development
• Driving security and compliance: Embedding security in the development and production processes to manage application security (AppSec) and vulnerabilities
• Tracking production health: Quickly gaining insights into overall production health, team performance and service status
• Understanding DORA metrics: Enhancing developer productivity and velocity by understanding and tracking key DevOps Research and Assessment (DORA) metrics

Determine Who Will Use the Portal

The internal developer portal will serve three main user groups, each with distinct needs and responsibilities:

1. Developers: These are mainly junior and senior developers who are primarily responsible for coding and business logic. They leverage the portal to perform specific tasks efficiently.
2. Team leads and group managers: They are responsible for overseeing the developers. They require a comprehensive view of all project statuses and organizational context.
3. Dev managers: This group is responsible for higher-level management activities including product quality, cost tracking, security, compliance and productivity. They need quick access to project and product information.

I’ve explained how an internal developer portal helps developers, the most effective approach to roll it out, example use cases for developers and managers, and who will use it. Now it’s time to discuss how to encourage portal adoption.

Get Developers to Use the Portal

The successful adoption of the internal developer portal involves understanding the organization’s team structures and customizing the rollout strategy based on team goals. It is best to avoid a big-bang approach and instead start gradually. How?

1. Map the organization’s team structure: Identify workflow interdependencies and tailor adoption strategies accordingly. Understand which teams are more likely to be early adopters and which teams are more likely to immediately benefit from the portal.
2. Customize the rollout strategy: Begin by interviewing and surveying developers, select a focused use case, choose adoption metrics and monitor usage data to identify obstacles.
3. Pilot the portal: Leverage successful initial teams as champions to encourage adoption and expand the portal based on demand.

Take a Product Mindset

Transforming the internal developer portal into a powerful tool for developers and managers requires a product management mindset. Focus on gradual adoption and use cases that make implementation smooth, leaving room for continuous feedback loops and options for iteration. A portal-as-a-product mindset helps you lay the groundwork for a tool that genuinely serves its users.

For more insight, check out Port’s demo.