Leveraging product management strategies for your developer portal

We create Internal Developer Portals so that they can be the central hub for developers, used for simplified self-service access to all the tools and information developers need to build, deploy, and manage applications. This is the “holy grail” of Internal Developer Portals, since it reduces developer cognitive load, sets golden paths, ensures standards are met and more.

But while this sounds great in theory, in reality you don’t just create a developer portal and have developers immediately use it. The portal you build needs to be the right one. Engineering organizations have different needs and expectations about what makes developer lives easier. Some organizations need to provide K8s abstraction to developers, others have issues with developer onboarding. So while it may be tempting to just go ahead and build a state-of-the-art internal developer portal, it’s better to take a step back and plan what needs to be in the portal, much like what a product manager of the portal would do. Or to say this simply- you need to think like a product manager and get the right features for developers, and not (only) like an engineer that wants to create a perfect portal.

The way to achieve the desired state of trust and adoption of the portal by developers is by treating the portal as a product. This includes all steps of product management, from ideation all the way to launch, adoption and feedback loops. This approach complements platform-as-product approaches that treat the decisions surrounding the internal developer platform from a product management perspective.

In this blog post, we’ll explain how you can use a product management approach to determine how to set up your internal developer portal.

‍

The Internal Developer Portal as a Developer Enabler

Let’s start by looking at what the portal is supposed to achieve. Like any good product, your portal is supposed to make its customers’, i.e developers’, lives easier and solve their problems in a meaningful and valuable way. To be more specific, it should allow them to focus on their core development work and productivity, and get what needs to be done in the portal quickly and efficiently. 

For developers, this means:

• Reducing the cognitive load they experience when using DevOps tools or assets
• Centralizing and streaming workflows
• Reducing the time they are spending figuring out answers and solutions to the questions they have
• Just as importantly, it also includes letting them experiment and innovate because they have time and their minds are free.

For dev managers and leads, this means:

• Setting standards for best practices and terminology
• Shortening that painful onboarding curve

But what should you first focus on to get the portal to where it actually provides these benefits to developers and managers?

‍

Deciding How to Rollout the Developer Portal

While a developer portal can cover almost all developer routines, from onboarding to consuming IaC or managing permissions, we need to decide on a strategy of what needs to be in the portal once we launch it. To do this, we do not focus on portal elements - such as “getting the software catalog in shape” or “creating automations” but rather focus on driving end-to-end experiences (what they are, we’ll show later in this blog). Each use case (developer experience)  should encompass all portal elements - from the catalog, through developer self-service actions, manager dashboards, scorecards and automations. In essence, we changing one developer routine that was done outside the portal, with a different developer routine, in the portal.

The best approach is to first choose a smaller subset of use cases that cover real needs in the organization, servicing real developer needs. This is very similar to the minimal viable product approach. Once the MVP is done, we can add portal functionality over time, driving adoption.

Similarly, manager needs - from cost control to engineering quality initiatives - also evolve. So we need to define a manager portal MVP and grow it over time.

The next step would be to identify additional use cases, and document them in a portal roadmap. Prioritizing these use cases will depend on the engineering culture, the pains and goals of the org (e.g. a migration to K8s).

For each portal phase, there needs to be a process of training, communication and a soft launch until the portal is generally available.

Portal success metrics should be defined and measured too.

‍

How to Get Started: Jobs to Be Done

The first step of turning the Internal Developer Portal into a life-simplifying, problem-solving solution for developers is to determine what it is supposed to do. This is where the “Jobs to Be Done” framework comes in. The “Jobs to be Done” framework is used for identifying, defining, categorizing and managing customer needs, as a way to ensure the product adds value and will succeed in the market. This is done from a prism of understanding the jobs customers are trying to get done. These jobs can be functional, emotional, or even social.

Therefore, instead of merely adding features based on assumptions, the Jobs to Be Done framework encourages us to start by identifying the jobs or tasks we want developers to accomplish, based on their actual needs. 

Once you complete these sentences, you’ll actually end up with user stories. Here’s one example:

“Instead of taking 2 hours to deploy a service, developers can scaffold it in the portal.”

We now have a “scaffolding service” user story. 

The next step is actually pretty simple. We need to understand how people “do this job” today, how bad the current way is (the negative impact of doing things the “bad” way), create more user stories, and prioritize. Each sprint can cover approximately 2-3 user stories. 

‍

Internal Developer Portal Use Cases

The Internal Developer Portal serves developers (mostly “mortal developers”) in a variety of situations and circumstances in their day-to-day. The top use cases include:

• Complying with Internal Development Standards - Internal Developer Portals can help with the driving and adoption of development standardization by providing golden paths and standards for developers to follow. This helps produce quality code that is secure & compliant, effortlessly.
• Bringing Features to Production - Accelerating time-to-market is top of mind for organizations. Internal Developer Portals offer developers a step-by-step experience, from IDE to production, making work smooth, efficient and compliant.
• Consuming IaC - IaC provides scalability and efficiency advantages to engineering organizations. IDPs can help adopt IaC by creating a developer self-service interface with IaC under the hood.
• Incident and on-call management - IDPs can transform the on-call experience by providing a structured and efficient environment for addressing issues. This includes features for triggering an incident, understanding health metrics, performing root cause analysis, and more.
• Interacting with K8s - Abstracting Kubernetes can significantly reduce the cognitive load for developers. With an IDP developers should be able to easily operate, troubleshoot and optimize the K8s stack for optimized use of K8s.
• AppSec Posture management - Letting developers easily access vulnerability insights and understand service delivery to get app sec teams off their backs.
• Managing Feature Flags - Feature flags let developers easily toggle, test, and deploy features. The IDP simplifies the process by enabling feature to service in production, scheduling feature flags, approving flags, setting flag triggers, and more.
• Keeping Up with Service Health - An IDP provides developers with the ability to monitor, manage and maintain optimal performance and reliability across all services.
• Understanding Internal APIs - Streamlining internal API development, ownership, management, and documentation.
• Permissions - Permissions management is a painful development responsibility. With an IDP, they can grant instantaneous, granular permissions, to databases, environments, tooling, cloud, and customer accounts, as needed.

Internal Developer Portal Use Cases for Dev Managers and Leads

Dev tool managers can also benefit from using the Internal Developer Portal. Some of the top use cases include:

• Staying on top of costs - Tracking and optimizing costs in context, by developer, team, service and environment, to the micro-budget level.
• Onboarding new developers - Reducing time to onboard by providing an organized experience to new hires, with all the guardrails they need.
• Driving engineering quality - Setting initiatives to improve production readiness, code quality and anything in between. This is done through standard communication, scorecards, showing ‘next best actions’ and reporting.
• Driving security and compliance - Controlling AppSec and vulnerabilities by ensuring security is embedded in both development and production
• Tracking production health - Getting quick insights on overall production health, in context, by team, developer and service.
• Understanding DORA metrics - Driving developer productivity and velocity by understanding metrics and tracking the portal’s impact.

Personas: Who Will Use the Internal Developer Portal?

The Internal Developer Portal will serve developers, and we’ve also discussed “dev managers” to some extent. But the “Developers” category is actually a wider-encompassing one that is made up of sub-groups. Each sub-group operates differently and has varying requirements based on its responsibilities and the expectations from them within the organization. Consequently, they have different needs from the Internal Developer Portal.

There are three main types of developers that will use the Internal Developer Portal in different ways. They are:

1. Mortal Developers - Junior and senior developers responsible for the tasks of coding and business logic.

How do they use the portal? They visit the developer portal with specific goals, such as moving code to production, bug fixing, or enhancing performance.

How can the portal product be improved for them? 

• Create intuitive progress flows (“golden paths”) so they know where they are in the flow
• Ensure consistency in terminology across different systems
• No context switch - stay within a single system

2. Team Leads and Group Managers - . They are responsible for overseeing "Mortal Developers." They have a data-centric approach, seek to gain insights into project statuses and oversee multiple projects.

How do they use the portal? They require a comprehensive view of project statuses, as well as the larger organizational context.

How can the portal product be improved for them? 

• Integrate with project management tools
• Enable them to provide feedback

3. Dev Managers - They are responsible for the higher-level management of the product and managing the “Mortal Developers”. This includes ensuring product quality and health, tracking costs, managing security and compliance, driving and measuring developer productivity and tracking developer onboarding.

How do they use the portal? They need a quick and immediate view of the status of projects and the product, coupled with insights, so they can easily prioritize tasks and manage competing needs.

How can the portal product be improved for them? 

• Add dashboards
• Integrate with organizational systems - HR, finance, Jira, etc.

‍

The Internal Developer Portal MVP

Now that it’s clear who we are targeting and what we expect them to achieve, it’s time to start developing the portal. Rather than building a full-blown portal, it’s recommended to start with an MVP for your chosen use case, just like with any other product.

The MVP will enable us to gather user feedback early in the process and the flexibility to adapt to changing requirements.  Running this process on each of your use cases is a more cost-effective and less risky approach than developing and launching a full-blown product. We’ll be able to iterate on improvements based on real-world usage and feedback, to ensure a more effective and user-friendly final product. 

‍

5 Steps to Creating Your Developer Portal’s MVP

1. Form an initial software catalog

The software catalog is a centralized metadata repository for all software-related information. Within the catalog, developers can see all operational components in one place, including microservices, cloud resources, CI/CD data, Kubernetes clusters, etc. The catalog serves as a reliable source of truth for development processes and developers can query it for specific information. The catalog’s structure is shaped by blueprints and relationships and it is continuously updated to maintain reliability.

2. Enrich the data model

A data model represents how an organization's environment and infrastructure are laid out and constructed. Its aim is to simplify the understanding of the interdependencies in the SDLC tech stack. By doing so, we can answer questions such as how are cloud resources connected to test environments where a particular service is running, all within a larger domain.

The data model is imported into the Internal Developer Portal so developers can find everything they need in the portal. Therefore, enriching the data model means adding more valuable data, which can help optimize the use of the portal.

3. Create your first self-service action.

Internal developer portals aim to reduce cognitive load for developers. This is done by providing access to self-service actions, which enable them to work efficiently with appropriate guardrails. Self-service is one of the cornerstones of an Internal Developer Portal.

Designing an effective self-service section in the portal involves creating an intuitive UI flow within the portal and loosely integrating it with the underlying platform responsible for executing self-service actions. Developers receive feedback on their actions, including logs, relevant links, and the impact on the software catalog. Additionally, the system can indicate if a self-service action is pending manual approval.

4. Enrich the data model with additional data sources

A software catalog's core model can also help additional users, such as DevOps engineers and managers. This can be done by incorporating more resource information related to underlying infrastructure or quality initiatives or providing data that enables them to better understand and manage engineering quality initiatives. This requires adding more extensions and data.

5. Add scorecards and initiatives

The ability to define scorecards and initiatives and drive engineering quality. With scorecards, teams can visualize service maturity and engineering quality of different services in a domain and understand how close or far they are from reaching a production-ready service.

‍

Adoption and Culture: How to Get Developers to Use the Portal 

The Internal Developer Portal is ready for use, finally. But will it be adopted and used? A product mindset can help here as well. To address these challenges, a two-step process is recommended.

1. Map and comprehend the team structure within the organization. Understanding how teams interact in your organization is key to identifying workflow interdependencies. This can help tailor IDP adoption strategies.

A good mapping framework to start with is with the four types of teams delineated in "Team Topologies: Organizing Business and Technology Teams for Fast Flow" by Matthew Skelton and Manuel Pais. These are: stream-aligned teams, enabling teams, complicated subsystem teams, and platform teams. Then, you might identify the onboarding platform teams first can create a solid foundation for stream-aligned teams.

2. Customizing the rollout strategy to align with the goals and structures of your teams. Avoid the big-bang approach and start slow:

• Conduct developer interviews and surveys to gain insights into their needs and pain points. 
• Select an initial focused use case to avoid overwhelming them with the portal.
• Choose the metrics that will determine whether adoption was successful. E.g, number of developers that use the portal, the number of actions taken, the time saved by using the portal, amount of positive feedback given, etc.
• Monitor usage data to identify adoption obstacles and gather feedback through surveys and user testing. 
• Leverage successful initial teams as champions to encourage adoption.
• Finally, gradually expand the portal based on demand rather than on a rigid schedule.

In addition, avoid the following pitfalls:

• Ensure the IDP integrates into existing developer workflows. For instance, if the information displayed in the portal, such as the running services view, does not accurately reflect the real state, developers can become confused and disengaged.
• Start by focusing on features that enhance developers' work (the MVP approach).
• Lack of support from organizational leaders can result in low prioritization and limited engagement from developers, who may question the portal's utility. Therefore, it is imperative that executives actively reinforce the value of the developer portal.

‍

What We Covered and Next Steps

Transforming your Internal Developer Portal into a centralized hub for developers is not a trivial undertaking, but the payoff is immense. The key is approaching the portal with a product mindset. This includes a complete lifecycle that involves Jobs-to-Be-Done, use cases, and MVP and gradual adoption with continuous feedback loops. By doing so, you lay the groundwork for a tool that genuinely serves its users.

Ready to get started?