Golden paths: the paved road, not the portal
A portal is a side effect. The real product is the paved road from "I have an idea" to "it's running in production" — how to design the first one and know if it's working.
Teams that set out to "build a developer portal" tend to end up with exactly that: a portal. A nice catalog page, a service directory, maybe a scorecard. What they don't end up with is engineers actually shipping faster, because a directory of services doesn't remove any of the manual work standing between an idea and production. The portal is a side effect. The product is the golden path — the officially supported, well-documented way to do a common task, opinionated by design so there are fewer decisions for the engineer and one thing for the platform team to maintain and secure.
Start from the developer journey, not the ideal architecture
The golden path isn't a hypothetical best-practice flow someone whiteboards in a design review. It's the automation of the actual path an engineer takes today from "I have an idea for a service" to "it's running in production" — every manual step, every approval, every Slack message required, mapped as it really happens. If nobody's walked that path recently, the platform team is building against a guess, and guesses about internal processes are wrong more often than anyone expects.
Pick the first one on frequency, not ambition
The highest-leverage first golden path is almost always "spin up a new service" — not because it's the most interesting problem, but because it touches every team, has an obvious before/after, and doesn't require resolving organizational disagreements (data ownership, security policy for databases, whatever) to ship. Prove the model somewhere uncontroversial before spending political capital on the harder ones.
Guardrails, not gates
This is the distinction that separates a golden path from a compliance process wearing a golden path's name:
- A gate blocks and waits for a human — an approval step, a review queue, a ticket.
- A guardrail makes the unsafe path harder to reach than the safe one. The scaffolding template already has the security defaults baked in, so there's no insecure option to accidentally choose.
Gates create queues. Guardrails preserve self-service while still enforcing the organization's standards — the security review already happened, at template-design time, instead of happening again for every service that uses the template.
The template is the golden path
Backstage software templates (or an equivalent scaffolding tool) turn "create a new service" into a form: name, owner, language — and the template generates the repo, the CI pipeline, the initial manifests, and the catalog entry in one action. This matters because it makes the golden path executable rather than documented. A wiki page describing the paved road is not the paved road; an engineer who has to read documentation and then perform twelve manual steps correctly has not been given self-service, they've been given a checklist.
Governance nobody remembers to plan for
As the template library grows, someone has to own deprecation. Templates drift from best practice over time — a base image goes EOL, a pattern gets superseded by something better — and without an owner and a review cadence, the catalog quietly fills with templates nobody trusts. The moment that happens, engineers route back to manual setup, and the platform's adoption number starts sliding without anyone noticing until a quarterly review.
What "working" looks like
Two numbers, tracked over time: the percentage of new services created via the golden path versus manually, and time-to-first-deploy for new services. If adoption is low, that's a signal to go interview users about what's missing — not a signal to mandate usage. A mandate without a working golden path produces compliance theater, not trust, and trust is the thing that actually drives adoption once the mandate is quietly dropped or unenforced.