Golden paths: the paved road, not the portal
A portal is a side effect. The 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 a portal: a catalog page, a service directory, maybe a scorecard. Engineers don't ship faster, because a directory of services removes none of the manual work 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 the engineer has fewer decisions to make and the platform team has one thing to maintain and secure.
Start from the developer journey, not the ideal architecture
The golden path isn't a best-practice flow someone whiteboards in a design review. It's the automation of the path an engineer takes today from "I have an idea for a service" to "it's running in production", with every manual step, approval and Slack message mapped as it happens. If nobody has 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 best first golden path is almost always "spin up a new service". It's rarely the most interesting problem, but it touches every team, has an obvious before/after, and doesn't require resolving organizational disagreements (data ownership, security policy for databases) to ship. Prove the model somewhere uncontroversial before spending political capital on the harder ones.
Guardrails, not gates
This is what separates a golden path from a compliance process wearing its 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 choose by accident.
Gates create queues. Guardrails keep self-service and still enforce the organization's standards, because the security review happened once, at template-design time, instead of 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 with name, owner and language. The template then generates the repo, the CI pipeline, the initial manifests and the catalog entry in one action. That makes the golden path executable instead of 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 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: a base image goes EOL, a pattern gets superseded. Without an owner and a review cadence, the catalog fills with templates nobody trusts. Engineers then go back to manual setup, and the adoption number slides until someone spots it at a quarterly review.
What "working" looks like
Track two numbers 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, interview users about what's missing instead of mandating usage. A mandate without a working golden path produces compliance theater instead of trust, and trust is what drives adoption once the mandate is dropped or no longer enforced.