3 Common Pitfalls When Adopting an Internal Developer Portal

Lately, the software industry has been hearing all the benefits that an internal developer portal (IDP) brings as a central component of platform engineering where developers can access tools, services, and information that they need to build and deploy applications. Implemented well, it reduces cognitive load and streamlines workflows for developers. 

One of the most popular ways to build an IDP is by using the Backstage library. Backstage is growing rapidly and now has more than thousands of adopters. However, for every successful adoption, there are several others that fail.

After talking to hundreds of companies that are looking to have an IDP, I’ve noticed several pitfalls in this journey. Let’s take a look at some of the common challenges companies face when adopting or building a developer portal to help inform your choices if you are looking to start the journey.

1. High Level of Effort and Maintenance Required 

We have seen customers try to manage their developer portal without even assigning a full-time engineer, let alone creating a dedicated team. We’ve never seen this work well. They end up giving up on the project due to the overwhelming amount of effort required. Looking at a recent Reddit thread, the number one highlighted pitfall is “underestimating the amount of effort to maintain Backstage itself.”

If you follow Gartner’s advice or even look at Backstage docs on strategies for adopting, you’ll find that you will need an average of 2.5 engineers (a frontend engineer, a backend engineer, and at least some part-time commitment from a DevOps engineer) to get started with your first few internal teams. Plus, an additional product person always helps the team understand how to prioritize the right problems that can be solved by their internal developer portal.

Even after setting up the team, the amount of knowledge required to maintain an IDP can be significant. Since many available tools are new, they lack appropriate documentation and content to support the needs of maintainers. Even basic monthly upgrades leave people scratching their heads to figure out how exactly they should implement them. However, the payoff for the level of effort needed is huge, with streamlined workflows and less cognitive load on developers vastly improving time to production.

2. Extensive Customization is Essential, Yet Labor Intensive 

No two developer portals look the same across companies. Every company has a unique set of challenges, so it’s necessary to customize their developer portal. The level of customizations that are needed by teams exceeds what a SaaS platform would usually provide, as it would be very costly for them to maintain them for all users. The list includes:

• User interface (UI) components and views
• Menu and sidebar items
• Ability to pick and choose plugins or write their own
• Updating catalog with components from an existing source of truth
• App’s theme, branding, and look-and-feel
• Unique workflows (e.g., service onboarding), and the ability to write code in them
• Search across internal tools
• Complex permissions policy around usage, such as role-based access control (RBAC), governance, etc.

Due to such requirements, there are not many providers offering a complete end-to-end IDP experience that meets enterprise needs.

3. Internal Adoption Requires Strategic Evangelism

Adopting an IDP takes time and requires a strategy. By launching a new portal, developers don’t always understand why they should start using it alongside the dozens of other portals that they already visit regularly. It takes time for them to alter their ways of working. A good adoption strategy should communicate the goal of improving developer productivity and happiness.

Even in the same organization, development teams face different sets of problems. For example, some people might be interested in observing deployments for their software while others want to observe the latest builds, explore docs, check API dependencies, and so on. 

Developers need to see how exactly this new portal fits their use cases and solves their problems. That’s why it takes some time to work with them and show how exactly an IDP and its processes can improve their experience.

Join Us to Explore How We Can Advance the IPD Journey 

Are you looking to adopt an IDP  but unsure of the challenges you may face? As we keep hearing more from our customers, we’re exploring ways in which Harness can help with your developer portal journey. If you’re interested, let’s talk. Reach out to us at idp-interest@harness.io or on our Community Slack (#internal-developer-portal) to discuss more!