A developer portal is only as good as its catalogue, and catalogues rot

The portal launches with enthusiasm. Forty services appear in the catalogue, each with an owner, a README and links to its dashboards. Eight months later, twelve of those services no longer exist, six new ones are missing, a third of the owners have changed team, and engineers have gone back to asking in chat who owns the payments API.

Nothing was wrong with the tool. The catalogue was maintained by humans, and humans update a catalogue exactly as long as someone is watching.

The three problems it genuinely solves

Be specific about these, because a portal justified as "developer experience" has no way to be evaluated.

Finding who owns a service. At three in the morning, or when a vulnerability report arrives, or when you need to deprecate an API, the question is who owns this and how do I reach them. In an organisation past twenty or thirty services this is genuinely hard and genuinely expensive, and it is the problem the catalogue exists to solve.

Creating a new service with the right scaffolding. Software templates generate a repository with the pipeline, the observability wiring, the security defaults, the ownership metadata and the deployment configuration already correct. The value is not saving an afternoon of setup, it is that the fiftieth service is configured the same as the first rather than copied from whichever one the engineer happened to look at.

Documentation that lives with the code. Docs written as markdown in the repository, built and published alongside the service. Documentation in a wiki is out of date because updating it is a separate act; documentation in the repository at least appears in the pull request that changed the behaviour.

If you cannot point to which of these three is your problem, you do not need a portal yet.

The catalogue must be fed, not filled

This is the difference between a portal that survives and one that is abandoned, and it is a single design decision.

Make each service's metadata a file in its own repository, discovered automatically. The team that owns the code owns the entry, it changes in the same pull request as the change it describes, and a service that is deleted takes its entry with it.

Then go further and derive what you can from systems that are already true. Ownership from the code owners file. Deployment status and version from the deployment system. Dependencies from the service mesh or from tracing data. Cloud resources from the infrastructure definitions. Everything you derive is one thing that cannot drift.

The rule that keeps it honest: if a field has to be typed by a human and is not visible to that human in their daily work, it will be wrong within two quarters. Either derive it or delete it.

Track catalogue freshness as an actual metric. The percentage of entries whose source repository has been touched in the last ninety days, and the count of deployed services with no catalogue entry. If nobody watches those two numbers, nobody is maintaining the catalogue.

Templates are where the payoff is

Of the three problems, scaffolding is the one with the clearest return, and it is the one to start with.

A template that creates a repository with the pipeline, a Dockerfile, health endpoints, structured logging with trace correlation, the ownership file, a dashboard and a starter runbook turns a set of standards from documentation into a default. Engineers get the correct setup by taking the easy path, which is the only reliable way standards spread.

The failure mode is templates that drift from the current standard, so a service created last year has the old pipeline and nobody updates it. Version templates, and provide a way to see which services were created from an old version. Some teams go further and make parts of the scaffolding a shared module that services consume rather than copy, which turns an update into a version bump.

This is the same reasoning as module design in Terraform: copied scaffolding diverges, consumed scaffolding does not.

The cost people do not plan for

Backstage is a framework, not a product you install. You deploy it, you write plugins, you maintain it, you upgrade it, and upgrades in a plugin ecosystem occasionally break things.

That means a named owner and a fraction of a person permanently. A portal with no owner is the most predictable abandonment in platform engineering, because it degrades slowly and nobody notices until it is useless.

Budget honestly: a few weeks to a first useful version, and ongoing maintenance thereafter. If you cannot commit to the ongoing part, do not start.

There are managed and commercial alternatives now, including hosted Backstage offerings and other internal developer portal products, and the trade is the usual one: less control and less customisation for much less operational load. For a team that wants the catalogue and the templates without the framework, that is frequently the right call.

When a repository and a README are enough

Under about fifteen services with one or two teams, a portal is overhead. The answers it provides are already in everyone's head, and the catalogue is a spreadsheet that is correct because someone can see all of it at once.

The cheap version that covers most of the value: a code owners file in every repository, a template repository people clone, a single page listing services with owners and links, and a convention that docs live in the repository. It costs nothing and it degrades gracefully.

Adopt a portal when the question "who owns this" stops having an obvious answer, which in our experience is somewhere between twenty and thirty services or when the second or third team arrives.

The things people forget

• It is not a substitute for ownership. A catalogue entry naming a team that does not really own the service makes the problem worse, because now it looks answered.
• Access control matters. A portal aggregating cloud resources, pipelines and dashboards becomes an attractive single view of your estate for anyone who gets in.
• Adoption is the hard part. A portal nobody opens is worse than no portal, because it absorbed the effort. Put it where engineers already are and make one thing genuinely easier on day one.
• Plugins age. Every plugin is a dependency with a maintainer who may move on.
• The scorecard temptation. Maturity scorecards are popular and become a game. If you use them, measure a small number of things that genuinely matter, such as whether a service has an owner and a runbook.

What to do this week

Pick three services at random from your production deployments and try to answer, in under two minutes each and without asking anyone, who owns it and where its runbook is. Time yourself. If any of the three takes longer than two minutes, you have measured the problem a catalogue solves, and the first fix is a code owners file rather than a platform. We work through this in the platform phase of a cloud engagement.