Platform Engineering Is Not about Building Fancy UIs

If I had to name the single biggest misconception some people have about platform engineering, it would be that the result of a successful platform engineering endeavor is a shiny user interface with lots of buttons to click and dashboards to look at.

Many people conflate developer portals and service catalogs with internal developer platforms (IDPs), but they aren’t the same. And there are real consequences to the confusion. At best, that shiny UI allows organizations to gain only a small part of the return on investment (ROI) they can get from platform engineering.

In 2022, I spoke with roughly 300 platform engineering teams. Many of these teams started their platform engineering journey with building a developer portal. However for 95% of them, other platforming initiatives would have had a bigger impact on developer productivity and ROI. Less than 20% of the teams see developers actually adopt and use the developer portal.

Developer Portals vs. Service Catalogs vs. Internal Developer Platforms

In 2022, Gartner clarified the relationship between developer portals and internal developer platforms:

“Internal developer portals serve as the interface through which developers can discover and access internal developer platform capabilities.”

For example, Netflix built a developer portal on top of its existing platform tooling.

An internal developer platform is the sum of all tech, tools and processes that a platform engineering team binds into a golden path for developers. The golden path reduces cognitive load and drives standardization by design. An IDP doesn’t even need to have a user interface. IDPs are about so much more than aggregating information and displaying it — from configuration and infrastructure management to environment and deployment management. Designing IDPs is about listening to what developers actually need on a daily basis and building solutions that address those needs. A developer portal can visualize the underlying platform, but it is not a necessary component of an IDP.

A developer portal or service catalog is a user interface that pulls data from several APIs and consolidates them against different views. A service catalog shows you a list of available services, which APIs they feature and the owner of the service. It pulls and aggregates the metadata from GitHub, ticketing systems and continuous integration (CI). Service catalogs often have a “templating gallery,” which is a more or less fancy collection of GitHub templates and dashboards.

Why Do Organizations Focus on Developer Portals and Service Catalogs?

If developer portals and service catalogs aren’t necessary, why do so many organizations focus on building them first? Here are some of the most common reasons I’ve seen:

• It feels obvious: When organizations start their platform journey, they tend to think about easing pain points in chronological order. The first thing that comes to mind are the tasks you complete first. For the life cycle of an application, that could be creating a service. For the developer, it’s usually onboarding. Many organizations choose to start automating here first.

• Is presentable: Dashboards are something you can show to your managers, especially if they don’t have a technical background. Visualizations are significantly easier to explain and sell than restructuring configuration management. But that doesn’t mean it makes more sense.

• Everyone has an opinion on interfaces: While there are comparably few people in the platform engineering space who have an in-depth understanding of how to architect internal developer platforms with regard to underlying technologies and real pain points like config management, many more have an opinion on interfaces. As a result, there is more talk about interfaces than about really deep problems in the developer experience.

Why Do Developer Portal and Service Catalog Endeavors Often Fail?

After investing time and resources into developer portals and service catalogs, many organizations are disappointed with the results. Here’s why:

• Developers hate “yet another interface.” They want to stay in code, in their git-push lane, and operate fast and without interruption. You can build the most beautiful UI, but that doesn’t mean anyone will regularly look at it. I looked at the usage metrics of the portal of a very large e-commerce player and found that, on average, developers were using exactly one function (search) once a year to check whether what they were building had been built before.
• The tangible benefits are low. The most common use case I hear is “we want to standardize the creation of new services.” Let’s assume you create an insane 1,000 new microservices a year. How do you do this today? Probably by just cloning GitHub templates. Because portals themselves are basically just UI frameworks, all they do is call other APIs. So if you implement the functionality of “creating a new service by clicking on a button,” this button will call the GitHub templating API and clone the linked sample repo. Building a portal using the most frequently used open source frameworks takes realistically six months for, at the absolute minimum, two full-time employees (FTEs). But where’s your impact? Are you gaining 10 seconds per service creation? One minute, even? Let’s say for some miraculous reason it’s 1 minute, and we take the 1,000 services and two FTEs that we pay $100,000 a year. Then your ROI is still at a wildly -80%, and remember this assumes we are creating 1,000 services every year! Congratulations, you just wasted time.
• Portals and service catalogs are also notoriously complex to implement and keep up to date. Developers will constantly circumvent, and a dashboard with wrong data is probably worse than no dashboard. You will spend an enormous amount of resources and time trying to keep stuff up to date.

Platform as a Product Is the Way

Instead of focusing on building developer portals or service catalogs, you should prioritize the features that benefit developers the most. You can figure out which features your organization needs by taking a product approach. With a product approach, you aren’t going to start by building the stuff some influencer tells you to or whatever feels obvious. Instead, you start with user research. Go to your developers and ask them what they need or want to do.

Then it’s your responsibility to prioritize those concerns. One way to do this is by noting how often developers do a certain task every 100 deployments and how long it takes. You’ll wind up with a table that looks something like the one below.

Sample Calculation

*Per 100 deployments. Source: https://humanitec.com/blog/top-10-fallacies-in-platform-engineering

You can use this table to figure out the ROI for your internal developer platform.

In most cases, I’ve found that two changes yield the biggest results. Making sure you really have basic CI/CD flows set up reduces toil and increases efficiency. Restructuring your configuration management from “static” to dynamic configuration management enables standardization by design, separation of concerns and continuous self-service with low cognitive load.

When Should You Still Build a Portal/Service Catalog?

This is not to say that there are no good reasons to build a developer portal. If your developers are creating an incredibly large number of services and resources and need to categorize them for inner-source endeavors, a portal is very beneficial. However, there are not many organizations that have the thousands of services and developers required to get to a positive ROI.

Sometimes you have to build a developer portal because management tells you to. You don’t have a choice. But if none of these cases apply to you, don’t waste your time focusing on the developer portal as a starting point. Instead, start with architecting your IDP. Your developers will thank you!