Blog
December 15, 2021 Marie H.

Building a Developer Portal for Your Platform Team

Building a Developer Portal for Your Platform Team

Photo by <a href="https://www.pexels.com/@olia-danilevich" target="_blank" rel="noopener">olia danilevich</a> on <a href="https://www.pexels.com" target="_blank" rel="noopener">Pexels</a>

Building a Developer Portal for Your Platform Team

There's a specific kind of organizational pain that hits engineering orgs around the 50-engineer mark. Things that worked on instinct and Slack DMs stop working. New engineers spend their first week asking "where does the auth service live?" and "what's the right way to set up a new microservice?" Tribal knowledge that lived in three people's heads becomes a blocker. The platform team becomes a bottleneck for information they should never have been holding in the first place.

A developer portal is the answer to this. Let me explain what that actually means and how to think about building one without drowning in scope.

Updated March 2026: Backstage moved from CNCF Sandbox to Incubating in 2022 and the plugin ecosystem has grown substantially. Managed Backstage offerings (Roadie, Spotify's own hosted option) have matured to the point where smaller teams no longer need to self-host if they don't want to. The SPACE framework has also gained wider adoption as a developer productivity measurement model.

Why Platforms Hit This Wall

The 50-engineer threshold isn't magic. It's roughly where the combinatorial complexity of services, teams, and ownership exceeds what any person can hold in their head. Things that break down:

Service discovery: nobody has a complete, accurate list of what services exist, what they do, who owns them, or how to reach their runbook. The list in Confluence is six months stale.

Onboarding: there's no single path for "how do I create a new service." Different teams do it differently. The new hire either copies an existing repo (and propagates whatever technical debt lives there) or spends a week asking questions.

Docs: technical documentation lives in wikis, READMEs, Notion pages, and the heads of the people who wrote the code. Finding the right doc requires knowing it exists.

Policy drift: security requirements, observability standards, and deployment patterns diverge across teams because there's no enforced golden path. You find out at audit time.

These are solvable problems. But they require investment in internal tooling that doesn't ship features directly, which makes them easy to deprioritize. The platform team's job is to make this case and then execute on it.

Backstage: The Emerging Standard

Backstage is Spotify's open-source developer portal framework, released in 2020 and now in the CNCF Sandbox. I'm watching it closely because it's the first credible attempt at an opinionated, extensible developer portal that doesn't require you to build everything from scratch.

The core concepts:

Software Catalog: a centralized registry of all your services, libraries, websites, pipelines, and infrastructure. Every entity is defined in a catalog-info.yaml file that lives in the repo alongside the code. The catalog ingests these via integrations with GitHub, GitLab, Bitbucket, etc.

TechDocs: documentation-as-code. You write docs in Markdown, store them in the same repo as the code, and Backstage renders them alongside the catalog entry. The key insight is co-location: docs that live with code stay current (or at least drift together, which makes the drift visible).

Scaffolder Templates: this is the golden path feature. You define templates for creating new services — the Scaffolder generates a new repo, pre-populated with your standard structure, CI config, catalog-info.yaml, and whatever else you want enforced. New service creation becomes a form fill rather than a two-day copy-paste exercise.

Plugins: the extension mechanism. There are already plugins for PagerDuty, Datadog, ArgoCD, SonarQube, and dozens more. The plugin model is what makes Backstage worth using as a foundation rather than something custom.

The catalog-info.yaml

Every service, library, or piece of infrastructure in your org gets a catalog-info.yaml in its root. Here's a realistic example for a backend service:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-processor
  description: Handles payment authorization and settlement
  annotations:
    github.com/project-slug: myorg/payment-processor
    pagerduty.com/integration-key: abc123def456
    backstage.io/techdocs-ref: dir:.
  tags:
    - payments
    - pci-dss
    - go
  links:
    - url: https://runbooks.internal/payment-processor
      title: Runbook
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: billing-platform
  dependsOn:
    - component:postgres-payments
    - component:fraud-detection-service
  providesApis:
    - payment-api-v2

This single file answers questions that previously required Slack DMs: who owns it, what system it belongs to, what it depends on, where the runbook is. The dependsOn and providesApis fields let Backstage build a dependency graph across your entire catalog. That graph is legitimately valuable for impact analysis ("which services will be affected if postgres-payments goes down?").

The annotation for PagerDuty means the Backstage PagerDuty plugin can surface active incidents for this service directly on its catalog page. Same pattern for Datadog metrics, ArgoCD deployment status, and so on.

What to Build First

This is where I see teams go wrong: they try to build everything at once and ship nothing. Backstage has a lot of surface area. Sequence matters.

Start with the Software Catalog. Get your existing services into catalog-info.yaml files and ingested. This alone is valuable — a complete, accurate service registry is something most orgs don't have. Don't add plugins, don't customize, just get the catalog working and accurate. This takes a few weeks, not months.

Second: golden path templates via the Scaffolder. Pick the one or two service archetypes that get created most often (Go HTTP service, Python worker, whatever your org actually uses) and build Scaffolder templates for them. This is where the platform team can encode your standards — the template generates a repo that already has your CI pipeline, your logging setup, your Dockerfile, and a catalog-info.yaml. New services start compliant.

Third: TechDocs. Once the catalog exists, people will want to find docs. Co-locate them with the catalog entries. You'll find that some services have no docs at all — now that's visible rather than invisible.

Add plugins incrementally after you have the basics. The PagerDuty and ArgoCD integrations are high-value because they bring operational context into the portal without requiring teams to open six different tabs.

The Build-vs-Buy Question

Backstage is not a SaaS you turn on. It's a React/Node application you deploy and maintain. Realistically it takes:

  • Initial setup: 1-2 engineers for 4-6 weeks to stand up Backstage, configure GitHub integration, and get the first 20 services into the catalog.
  • Ongoing: 0.5-1 FTE equivalent for maintaining plugins, updating Backstage versions (releases come fast), building new templates, and handling integration work.

That's not trivial. For a platform team that's already stretched, this competes with other work. The managed Backstage options (Roadie being the prominent one) trade money for operational overhead, which is a legitimate tradeoff for smaller teams.

The argument for self-hosting is customization. Backstage's plugin system is powerful and your internal plugins — connecting to your internal SSO, your internal deployment system, your ticket system — require code that can't live in someone else's managed instance.

My honest take: if you have fewer than 30 engineers, a well-maintained internal wiki plus good service documentation in GitHub is probably enough. Backstage pays off at scale. Don't solve the 100-engineer problem when you have 30 engineers.

Measuring Success: Developer Experience

How do you know whether the portal is actually helping? This is where the SPACE framework is useful. SPACE stands for Satisfaction, Performance, Activity, Communication, and Efficiency — a model from researchers at Microsoft and GitHub for measuring developer productivity in ways that aren't just "lines of code" or "tickets closed."

For a developer portal specifically, I track:

  • Satisfaction: developer NPS on the portal specifically (quarterly, short surveys). Is it actually useful or does it feel like compliance theater?
  • Time-to-first-deploy for new engineers: does onboarding get faster quarter over quarter?
  • Service coverage: what percentage of production services have a catalog-info.yaml? If it's below 80%, the catalog is unreliable as a source of truth.
  • Scaffolder adoption: what percentage of new services are created via templates vs ad hoc?

The last one is the most revealing. If engineers aren't using the Scaffolder, either the templates are wrong (they don't match how people actually want to build services) or they're unknown. Both are fixable.

A developer portal is infrastructure for your engineering organization. It doesn't ship features. It makes everyone who ships features more effective, and it makes the platform team's implicit knowledge explicit and discoverable. At scale, that's worth the investment.