Best Practices for Building or Deploying an Internal Developer Portal

Introduction

Developer experience and productivity are top-of-mind as organizations sharpen a focus on engineering efficiency. In a bid to become the central hub for developer interactions, Internal Developer Portals (IDPs) have landed on the short list of priorities for engineering teams everywhere. But without clear direction, engineering teams can struggle to deploy, drive adoption, and measure outcomes.

In this guide, we’ll draw on the hundreds of conversations we’ve had with engineering teams that have evaluated, built, or bought an internal developer portal to offer a new take on what might be missing from your IDP strategy.

What’s driving urgency for IDPs?

Internal Developer Portals are centralized hubs used by engineering teams to quickly catalog, evaluate, and build new services and resources according to defined best practice. A primary goal of IDP adoption is improving developer productivity, which can be summarized as the speed and efficiency with which developers build reliable software. With Gartner reporting a 325% increase in inquiries regarding “developer productivity,” it’s no surprise IDP popularity has risen in kind.

As for what’s driving near-frenzied interest in productivity over the last two years, the answer for most product-oriented businesses lies somewhere between three deeply interrelated themes unique to this particular moment in our economic and technological timeline:

Market State

A 2021 study showed that businesses in the top quartile of developer velocity outperform peers by 5x in revenue. This sobering statistic, combined with a pandemic-weakened global economy left 75% of business leaders in 2022 worried they could be displaced entirely by faster competition—up 18% from the year prior.

Tech Landscape

Thanks in part to an influx in remote work over the last few years, many organizations are exploring a shift to development styles that favor parallel work and async communication. 86% of organizations have adopted service-oriented architectures, while 96% are now using or actively exploring use of Kubernetes. However, the benefits of speed and autonomy associated with these shifts do carry non-trivial knock-on effects. Lack of guardrails to ensure quality at scale, and a steep learning curve for the “right” way to do things now jeopardize development velocity.

Evolving Developer Requirements

Increased competition and a quickly evolving tech landscape have put enormous pressure on developers to ship higher quality code, faster. While business leaders assert that the primary goal of developer productivity is to improve customer or business satisfaction, developers themselves say focus should shift further left—reduce toil, improve collaboration, and prioritize professional development.

The problem many organizations now face as a result of these interrelated factors is how to improve developer experience to ship higher quality code, quickly.

Varying approaches to IDPs

Internal Developer Portals have emerged as a solution to all three factors above—aiming to improve collaboration and reduce toil for devs, without sacrificing speed or quality. By now, most practitioners would agree that a strong Internal Developer Portal has—at minimum—four key features:

• Cataloging: Sync data from across your stack to provide an up-to-date view of information pertaining to internally developed software
• Scorecarding: Codify requirements for their services and resources to achieve standards of deployment readiness, operational excellence, security compliance, etc.
• Scaffolding: Speed paths to production with project templates and boilerplate code that reduce friction in service creation and onboarding.
• Reporting: Provide a view of progress to goals. Easily identify gaps in alignment to make better decisions about resources and timelines.

Where IDP platforms (including homegrown) are beginning to diverge is less in features on offer, and more in how these features are built, integrated, and aligned to developer workflows. Three primary philosophies have emerged related to how quickly solutions can be stood up, versus how easily developers can manipulate underlying data models, and build new capabilities on top. While the IDP market is still evolving, solutions that have already rotated too far towards one or the other carry the most risk of troublesome program setup, or inadequate adoption.

“Rigid Opinion” IDPs

IDP solutions that place heavy emphasis on low-touch quick-wins in observability, scoring, and reporting resonate strongly with executives eager to see change in development quality. Reduced complexity enables faster set up, but also limits ability to meet complex use cases, or adjust workflows as data and processes evolve. Commercial solutions in this category also tend to be light on features that accommodate preferred developer workflows, like consolidated prioritization and alerting. As a result, teams may see poor long-term adoption and ultimately—little impact to development quality or velocity.

“Unopinionated” IDPs

IDPs that prioritize extensibility aim to reduce deployment barriers without requiring developers to abandon preferred workflows. However, the price of increased optionality is significant investment in both initial build and on-going maintenance. These solutions can also carry a higher risk of model drift and workflow silos relative to the team’s broader tooling ecosystem, and as a result, require close attention to how data is integrated and used, as well as how much time is spent extending capabilities.

“Flexible Default” IDPs

When an organization can improve quality through—rather than at the expense of—a positive developer experience, is when they’re most likely to see success from their IDP. But it’s not easy to balance standardization with the flexibility required to suit developer preferences and evolving ecosystems. IDPs that provide logical defaults in data models and developer workflows can reduce up-front setup and ongoing maintenance, without limiting future use cases. However, these solutions still require tight stakeholder alignment on information architecture, use cases, and global versus fractional standards.

Five tips to ensure an impactful IDP program

Having only really achieved mainstream adoption in the last few years, IDPs are still short on precedent in ownership and operation. As a result, many organizations are struggling to answer questions like who should own the program, what use cases should be prioritized, and what capabilities comprise a list of requirements. After speaking with hundreds of engineering teams on the path to build or buy their own IDP, we’ve developed a list of 5 tips that should help any team ensure their efforts are fruitful.

TIP 1: Chart your approach

As noted in the section above, there are a variety of approaches to building Internal Developer Portals. However, whether your goal is to improve visibility, enforce standards of excellence, or unlock developer self-service—you can’t avoid the necessary work of solidifying your information architecture, understanding ownership, and agreeing on best practice. The Cortex Engineering Maturity Curve can be used to ensure strong foundations for your IDP program, so you can ensure your program will scale to meet any use case as your business evolves.

Aggregate

The first step to accelerating developer productivity is enabling immediate access to reliable, up-to-date information about the services and resources they use every day. Well before templating new assets, it’s important to understand what you already have, where it lives, who owns it, and how each relates to one another.

Assess

Once you’ve collected and categorized your services and resources, it’s time to think critically about their health. If you have existing standards, which are out of date? Which pose a risk to the business? If you’re interested in improving efficiency across certain teams, product lines, or offerings, you’ll want to begin thinking about what operational excellence should look like, and how that rubric varies across differing use cases.

Prescribe

Assessing the current state of your services is an important step towards service maturity. But as your team scales, use cases expand, scorecards grow in complexity, and initiatives are added with greater frequency, you’ll need a way to ensure compliance while removing any confusion about what to do next. The Prescribe phase is how the maturity curve scales with your organization, without draining your team’s time.

Enable

One of the final steps in a progression towards engineering efficiency is a repeatable and reliable method for creating new services according to best practice. This phase is what many developer portals were designed to optimize for—even before defining standards for service readiness and maturity. However, when tackled after setting standards of excellence, this phase results in DRYer code, speedier deployments, and a decreased rate of incident.

Optimize

To promote a culture of continuous improvement amongst developers, it’s important to provide—in kind—a platform that continually evolves to meet their evolving requirements. This phase therefore becomes incredibly attractive to platform architects, and platform product managers that can own metric monitoring, incremental improvement, and use case extension.

TIP 2: Map your information architecture

A recent Cortex market survey revealed that 67% of those struggling with IDP adoption pointed to “lack of internal alignment on information architecture” as the #1 blocker to forward progress. This is the very first step in the aforementioned Engineering Maturity Curve, but deserves its own section in this guide.

The way that data connects from across your developer ecosystem dictates how developers can see, understand, and act on requests to improve service health and alignment to best practice—making your information architecture the most important step in establishing your IDP program. While most teams understand that identifying data and dependencies is a key step in this process, many overlook the nuances of ensuring alignment with the rest of your ecosystem, while still creating opportunities to safely evolve how elements of your data relate to one another.

To begin, it’s useful to imagine drilling down from the action you ultimately want to enable, back through to what data is required for that action, and how it should connect. Ask yourself the following questions to begin sketching the outline of your requirements:

What do we want to do?

• What’s our key use case?
• Why is it a priority?
• How will we measure it?

Who is responsible for that work?

• How is my team organized?
• How does their organization change what they need to know or do?

What questions will we want to ask?

• What will we query when we need to know audit readiness, migration status, deployment state, etc?
• How often will we want to ask those questions?

What do we have today?

• What data is needed to answer questions and facilitate action?
• How do these elements already connect to one another? What other connections are necessary to drive the actions we outlined earlier?
• What hierarchy exists, or do we want to exist? What is the lowest level operation the teams above are accountable for?

TIP 3: Determine your ownership model

Understanding “who owns what” is still the number one use case for engineering teams investigating IDPs. Whether it’s to provide more immediate response during an incident, or ensure resources are maintained as standards change, ownership is at the center of every engineering initiative.

But it’s not as straightforward as it seems. Rapidly expanding teams, inconsistencies when members join or leave projects, and the fact that identity management is now often spread across multiple systems. makes it harder than ever to know who to call. Even existing monitoring platforms and IT Service Management (ITSM) systems lack context about how services are created, how well they align with current standards, and who owns them.

While determining (or more often—fixing) your ownership model is a critical step in IDP preparation, you don’t need to sort everything ahead of time. Your IDP can actually help create the structure and consistency you require.

But there are some common mistakes to avoid:

• Don’t make an IdP your IDP: Your IDP (Internal Developer Portal) does not need to become your IdP (Identity Provider). Ensure your IDP connects to your favorite identity provider to avoid duplicate work and inconsistent information.
• Don’t lock your model before your use cases. You can and should use your IDP to identify gaps in ownership within the context of the workflows you plan to enable, like service improvement, audit preparation, and new service creation.
• Don’t rewrite ownership paths. As with the first point, your IDP shouldn’t be considered a way around resolving existing ownership frameworks. Fix what you have globally first, and let those systems flow into your IDP.
• Don’t forget who doesn’t own is just as important as who does. Mass-blast notifications and emails about upgrades or incidents can be extremely distracting for those not directly impacted. What’s worse, relevant owners may have already learned to tune out these announcements, slowing time to respond. Granular ownership information therefore expedites initiatives and reduces noise.

TIP 4: Identify priority use cases and stakeholders

“Don’t ship your org chart” is a common phrase in product management to caution against letting poor organizational structures get in the way of excellent output. Your IDP program is no different. Involving multiple teams from the start can reduce risk of redundant solutions, or poor resource allocation. For example, you may learn that SRE and DevEx groups in different parts of the company have both embarked on initiatives to reduce developer toil by consolidating alerts from multiple tools. These solutions will be redundant, and could have been avoided by a unified approach to IDP ownership.

However, involving every potential stakeholder can feel a sure-fire way to never launch your program. That’s why it’s important to coalesce at the beginning, prioritize use cases together, and then determine levels of on-going involvement. Below, we’ll walk through an example 
IDP deployment strategy that illustrates how to introduce various stakeholders over a multi-phase timeline.

<div class="note">Every organizational structure is different. You may find it best to involve DevOps and Product Management earlier, and Incident Management later, for example. The below is for illustrative purposes only.<div>

Phase 0: Conduct your kickoff

Suggested Involvement: Everyone

Begin with a kickoff that involves all possible teams, where you decide which priorities are most pressing. Perhaps your platform team has an initiative to improve developer velocity, while your security team is wondering how they’ll get the visibility they need to complete your ISO27001. The kickoff meeting is where you’ll decide on which use cases can be tackled in parallel, how you’ll measure outcomes, and who should be involved. It’s also useful to nominate individual contributor representatives from each team of soon-to-be users, in order to ensure they understand what you’re trying to solve.

Phase 1: Establish standards

Suggested Involvement: Engineering, Platform, Incident Management, Security, SRE

Some of the earliest available use cases in an IDP’s lifecycle are ownership and as a result—incident management. For this phase, you’ll likely want to involve your DevEx, platform, and IM teams, to better understand how simply understanding service details and owners will improve the way they work. Understanding ideal workflows will also help you refine your information architecture, as outlined in earlier sections.

Once you’ve created the foundations for your catalogs, you’ll want to begin setting minimum requirements for the contents of those catalogs, which could include service maturity, security, and compliance. At this point, you’ll want to also include your Security and SRE teams to identify highest priority requirements.

Phase 2: Plan for enablement

Suggested Involvement: TPM, DevOps

Now it’s time to consider how you’ll enable your teams to take action that aligns with the requirements you’ve set forth in the previous stage. This involves sorting the templates and workflows you’ll want to create to enable self-service in service creation and provisioning. Doing so will enable you to tackle additional use cases like software migrations that require your team to not only bring existing assets into alignment with established standards, but build new services and resources according to those same standards.

Phase3: Optimization

Suggested Involvement: DevEx,Product

Phase Three is when you’ll be ready to refine or optimize your IDP workflows by extending functionality, and customizing experiences by team. Here you’ll want to involve the product team, and if you haven’t already—your Developer Experience team. You can invest more fully in your IDPs plugin framework to reduce context switching with new data and centralized reporting.

TIP 5: Ensure adoption

Of those that struggled to build or deploy an ICP, 20% pointed to “lack of developer buy-in.” That number jumped to 50% for homegrown initiatives, according to a recent Cortex market survey. While ensuring adoption is the “last” step in deploying your IDP program, it should be top of mind from the very beginning. Which solution you choose—what capabilities are available, how extensible it is, and how closely it aligns with preferred developer workflows—directly impacts how likely your team is to embrace your IDP as a central system of record.

According to Cortex market research, there are three main reasons organizations might struggle with IDP developer adoption:

• Lack of awareness: Individual developers often aren’t aware of IDP initiatives until they’re asked to use it. Even then, developers are often confused about which actions to prioritize, and how to use the portal as part of their day-to-day work.
• Lack of “bigger picture”: Devs might consider IDPs a distraction to their existing work—just “one more tool.” If they don’t have a clear understanding of their role in larger quality and velocity initiatives, there’s no reason for them to change the way they work.
• Lack of prioritization: 61% of developers surveyed say that noise from too many tools makes it difficult to know what to do, when. Without a mechanism to prioritize asks, it can be difficult to drive meaningful change.

To ensure your IDP delivers value to developers, we suggest you take the following measures:

• Alignment: Nominate leads from each team to be part of your initial kickoff to ensure you’re collecting concerns and workflow preferences from those who will be using the platform every day. Ensure they understand top initiatives, and their role in that work.
• Awareness: Ensure developers know what’s asked of them, and what steps to take to improve the quality of services, hit compliance requirements, or reduce duplicative work.
• Improvement: Let devs see how their peers are performing, and enable them to connect with one other to learn how to improve velocity, task management, and more.
• Integrations: Make integrations a first-class priority, to accommodate any developer workflow and use case as your team evolves. Reduce context switching by ensuring devs can see critical inputs from multiple sources all in one place.
• Prioritization: Make it easy for developers to understand which initiatives or parts of initiatives should take precedence over others. Help them to understand when tasks need to be completed by, and what’s at stake if the deadline slips.
• Impact: Provide and enforce standards with known outcomes for non-compliance, like inability to deploy until specs are met. Ensure requirements are clear, and impact known.
• Gamification: Add a layer of reporting to incentivize action and improvement. Make progress clear to developers, their peers, and team leads.

Cortex — The leading Internal Developer Portal

Cortex is the Internal Developer Portal unlocking productivity for teams on the path to engineering excellence. With a “flexible default” approach to connecting all the tools in your developer ecosystem, Cortex helps you get moving faster, while providing the flexibility to meet any use case. Unify your data, drive initiatives, and automate the path to incremental improvement in a way that actually fits how developers prefer to work.

<p class="text-style-label-2 text-color-purple">Catalogs</p>

<p class="heading-style-h4">Don’t repeat your logic</p>

Cortex’s Catalogs provide automatic discovery and mapping of services, resources, teams, and domains so users can quickly get answers to questions about ownership, documentation, dependencies, and more. With the richest integration library, Cortex accelerates the process of mapping your information architecture using relationships you’ve already built elsewhere. Keep what works, or redefine as needed—with a flexible plugin architecture that lets you build or extend connections to any other tool on your own timeline.

<p class="text-style-label-2 text-color-purple">Scorecards & Initiatives</p>

<p class="heading-style-h4">Drive progress on your timeline</p>

Cortex uses context from across your developer ecosystem to provide a rich picture of engineering productivity, efficiency, and operational excellence. Cortex Scorecards and Initiatives enable you to codify standards and drive progress against both short and long-term initiatives. From tool migration to audit prep, or operational readiness, Cortex’s flexible framework lets you build for any use case, and alert users to tasks that must be completed by specified deadlines.

<p class="text-style-label-2 text-color-purple">Developer Homepage</p>

<p class="heading-style-h4">Eliminate noise and make action obvious</p>

Ensure your team knows exactly what’s needed to execute immediate tasks and complete longer-term initiatives—both in and out of the Cortex platform. Cortex’s Developer Homepage aggregates information from across each developer’s owned services, resources, and related tooling to help them make better, faster decisions about where to focus their effort. In just a few clicks developers can assess service or resource status, view open PRs, investigate unresolved issues, and take action to bring their services and resources in alignment with organizational standards. Cut noise, eliminate context switching, and reduce mental load on each developer.

<p class="text-style-label-2 text-color-purple">Scaffolder</p>

<p class="heading-style-h4">Build better from the start</p>

Speed paths to production with project templates and boilerplate code. The Cortex Scaffolder brings scorecards to life by removing 90% of the friction faced when building services that meet your standards of readiness. Ensure Day 1 tracking with tight service and resource catalog integration. Speed migrations to new tools or systems like enforcing a change in secrets managers. And improve DevEx and productivity with “golden paths” and DRY code.

For more information on how Cortex can elevate your developer productivity initiatives, book a demo, subscribe to our blog, or join one of our education webinars on how to improve developer productivity at your organization.