Finding order in a sprawl of tools
Six years ago, Spotify’s engineering culture was built on autonomy. Teams chose their own stacks, their own tools, and their own workflows. That freedom had a cost: fragmentation. The only reliable way to learn how to do something was to ask a colleague. Internally, the company called it “rumour-driven development.”
As Spotify scaled, that approach stopped working. The infrastructure organization (referred to here as Platform) needed a way to promote alignment without mandating it—making recommended tooling easy to find, the path through it clear, and support obvious when engineers got stuck. The solution was the Golden Path, a concept first prototyped during a Hack Week as a tutorial for backend engineers.
The original pitch, from an internal Platform blog post, still holds up:
[We aim] to create great ways for a developer to work and build stuff at Spotify. One of our hard challenges is to unify all the different ways to use our infrastructure and provide tools that make sense to our many squads with very different needs.
[...]
[During Hack Week] eight top engineers gathered their forces and created a tutorial on the recommended way of using our services; it was named “The Golden Path”. This is the way we support an easy and streamlined way of working. If you are an adventurer you can of course leave the Golden Path and do your own thing, but then you will not have the same support. It should be easy to work at Spotify and this tutorial made that happen and brought gold to the people.
What the Golden Path is today
The Golden Path is now defined as the “opinionated and supported” route to building something—a backend service, a website, a data pipeline. A corresponding Golden Path tutorial walks engineers through that route step by step. There is no single tutorial for everything; instead, Spotify maintains one per engineering discipline, covering backend development, client development, data engineering, data science, machine learning, web, and most recently, audio processing.
Discoverability happens through Backstage, Spotify’s internal developer portal, where the blessed tools appear in the Explore section with filtering by discipline. The tutorials themselves are authored in TechDocs, Spotify’s docs-like-code system, and consumed within Backstage.
The goal is not to constrain engineers or impose standards for their own sake. The point is to eliminate reinvention. Teams with a Golden Path have fewer decisions to make and can focus their energy on the actual product. The concept has become so embedded in Spotify’s culture that it has spawned related terms—the Paved Road and Silver Path—though the Golden Path remains the target for everyone.
What makes the tutorials work
The Golden Path tutorials have become what Spotify considers its most important documentation. Several factors explain their effectiveness.
Written for new hires
Each tutorial targets a specific, known audience: engineers who have just joined Spotify. This fixes the assumed knowledge level and shapes the depth of explanation. Experienced engineers also read the tutorials—perhaps when moving into a new discipline or checking whether the current recommended approach differs from what they did years ago—but writing for newcomers keeps the instructions unambiguous for all readers.
A single, clear purpose
At one point, the team lost sight of what the tutorials were actually for. Were they a how-to guide? A demonstration of best practice? An educational tool? A reference? The answer, it turned out, was simpler than the debate suggested. As another product manager phrased it: “The Golden Path is the opinionated and supported path to build your system and the Golden Path tutorial walks you through this path.” That formulation settled the question and gave the tutorials focus.
Every step, in order
The tutorials document every action—click here, press enter, and so on. This can feel tedious to write and seem excessive to read, but omitting steps is far more likely to create confusion. A complete sequence also reveals the true length of the Golden Path itself.
Match the actual path
A recurring complaint is that the tutorials are too long. The honest response is that the tutorials merely mirror the actual Golden Path. If the path itself is long, the answer is to shorten it—to reduce the number of steps engineers need to take—not to hide steps in the documentation. Conversely, when a tool changes, such as the adoption of Kubernetes, the tutorial must be updated at the same time. The written path and the real path cannot diverge.
One tutorial per discipline
Spotify has considered other structures, such as splitting tutorials by job, with separate guides for testing, coding, and other concerns. The per-discipline model has won out, even in a world trending toward more T-shaped engineers.
Education, not just efficiency
If the Golden Path is simplified to the point where a task takes three clicks, the tutorial might shrink to three paragraphs—or disappear entirely. That would be a mistake. The tutorials are an educational tool, especially for new hires. While the Platform team should simplify the path to help engineers move faster, the learning goal remains important. Removing too much from the path hides too much under the surface.
Treated as a priority
The Golden Path tutorials are central to onboarding and are consistently among the most read and most used technical documents at Spotify. They are treated accordingly, and teams that maintain parts of them are told: if you have limited time for documentation, spend it on the Golden Path.
Continuous real-world testing
New engineers are expected to complete their discipline’s Golden Path tutorial within their first two weeks. Afterward, they participate in an Engineering Bootcamp, where they build an end-to-end product over a week using the tutorials as their foundation. This ensures nearly every new engineer exercises the material, generating constant feedback—not just on the documentation, but on the underlying Golden Path itself. That feedback loop is a valuable source of insight for the Platform organization.
What’s Next for Golden Paths
We’re proud of the Golden Path tutorials and how far the concept has come, but we also see plenty of room to grow. Below are three areas we’re exploring. The first two are active projects; the third is more of a long-term vision.
Fixing the Ownership Gap
Initially, each tutorial was owned by a dedicated technical writer. That model didn’t scale, and it pulled writers away from broader documentation problems affecting all of Spotify. So we moved to a centralized model to tackle those larger issues — which, predictably, created a second-order problem. Because each tutorial covers a specific engineering discipline, content ownership now sits across many different teams. That works fine on its own, but we lost coordination at the level of individual tutorials (which the writer used to handle) and at the level of the tutorial set as a whole (which the writers collectively managed). We have no plans to revert to the old structure, but we are actively looking for ways to restore that coordination without sacrificing the benefits of the centralized approach.
Golden State: From Guidance to Verification
We’ve been experimenting with a concept we call a Golden State: a list of checks engineers can run to confirm their systems are actually following the Golden Path. The ambitious end goal is to get most of the engineering organization on the Golden Path, which would meaningfully reduce fragmentation across our tech ecosystem. Less fragmentation means lower maintenance costs for teams, and when more people use the same approach, there’s a much higher chance we can automate upgrades for everyone. That’s something teams consistently ask for.
Product-Level Tutorials
Our tutorials today are designed for individual contributors. But individual contributors work in teams, and teams build products — features, experiments, company bets — that cut across multiple disciplines. The notion of creating Golden Path tutorials that serve as blueprints for building entire types of products is genuinely exciting, even if it’s difficult. It would mean shifting from single-user guides to multi-disciplinary team guides.
That one may be far off, though. As Dune fans might put it, the Golden Path is about bringing a singular, survivable future into being — and we’re working on ours one step at a time.
