Roadie's Backstage Weekly - Internal docs that actually help

Roadie's Backstage Weekly - Internal docs that actually help
By David Tuite • Issue #8 • View online
Why Spotify’s internal technical docs actually get used.

Backstage’s migration to the Backstage GitHub organization happened in earnest this week. One of the conditions of donating Backstage to the CNCF was that it would move out from under the Spotify GitHub org and stand on its own two feet.
The main Backstage project now lives at and some of the supporting components like the CLI for technical documentation (aka. TechDocs) moved into their own repos.
Now that TechDocs in Backstage works end to end, the focus has shifted to improving the user experience and increasing stability. If the success of the internal version of Spotify TechDocs is anything to go by, TechDocs V2 will be worth the wait.
TechDocs at Spotify has an interesting history. A few years ago, Spotify surveyed their developers and found that people were really struggling to locate technical information. The main problem was a lack of discoverability. Even if technical documentation did exist, it was so difficult to find that it wasn’t actually helping anyone.
An internal hackathon spawned the solution to the problem — a Backstage plugin for documentation hosting.
There were two parts to it:
  1. Tooling to allow developers to put their documentation into their GitHub repos, where it lives alongside their code.
  2. Tooling to take these in-repo docs and transform them into HTML that can be hosted inside Backstage.
Once launched, this hackathon project became one of the most successful projects they ever rolled out internally. Within 6 months, they had over 1,000 software components, websites and microservices documented. Today there are 2,400 documentation sites inside Spotify and over 1,000 people use them daily.
Within six months we had 1,000 different components, websites and microservices that were documented. It was just the fastest level of adoption I’ve seen in 25 years of trying to figure out how to solve this [problem]. I’ve never seen that, even at startups, at scale, at companies that are compliance-oriented; you have to hire whole teams of people to go do documentation.
Jim Haughwout - Head of Infrastructure and Operations at Spotify
Spotify’s approach to documentation for internal services has a ton of benefits:
  1. Documentation and code can stay in sync because the docs live in the same repo as the code. You can update both in the same pull request.
  2. Docs are easily discoverable. Everyone knows that Backstage is the place to go for documentation. Docs are indexed in Elasticsearch so you can easily find what you need.
  3. Docs are easily updated. If you’re reading a doc in Backstage and find a problem with it, you can click a button directly on the doc. This takes you to GitHub where you can commit a fix. If you can’t fix the doc yourself, you can highlight text in Backstage and click a popup button to create a GitHub issue to get the problem fixed.
  4. Metrics are easy to come by. When you have a single place where docs are read, you can start tracking how up to date they are and how often they are read. The numbers help motivate people to keep docs fresh and useful.
  5. Backstage shows you when the docs you are reading were last updated. When you can see how fresh they are, you can be confident they are correct.
TechDocs V2 for Backstage is in development right now. We can’t wait to see it!
Merged last week...
63 pull requests were merged last week. Here are the highlights.
Dependency visualization component
In a hint of fun things to come, Spotify frontend engineer Mikaela Grundin added a dependency graph component to Backstage #3236.
Internally, Backstage has dependency visualisation capabilities which look like this:
This functionality doesn’t exist in open source Backstage but hopefully this pull request is the first step!
Release 0.1.1
The alphas are gone #3140! 🎉 The core team’s focus for the rest of the year will be stability, and reducing the number of breaking changes in the Backstage API. To that end, they are also introducing a new stability index for packages which ship in the monorepo.
That’s all for this week. Get upgrading and good luck! 🚀
Did you enjoy this issue?
David Tuite
By David Tuite

Each week we send out the latest Backstage news, along with tips to help you get the most value from Backstage.

This newsletter is created by Backstage mega-fans. It is not affiliated with Spotify or the Backstage core team.

If you don't want these updates anymore, please unsubscribe here.
Powered by Revue
9450 SW Gemini Dr, PMB 78170, Beaverton, Oregon, 97008-7105, United States