The main Backstage project now lives at github.com/backstage/backstage
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:
- Tooling to allow developers to put their documentation into their GitHub repos, where it lives alongside their code.
- 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:
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.
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.
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.
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.
- 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.
for Backstage is in development right now. We can’t wait to see it!