Making Tech Documentation Better, Easier, And Less Boring
summary
Spotify builds a docs platform called Tech Docs inside Backstage that treats documentation as code with docs-as-code workflows integrates mkdocs Docker CI Kubernetes and Google Cloud Storage and ties docs to GitHub PRs and issues for instant previews and ownership metadata. A six person team rolls it out to roughly 400 services and reaches about half the company in six months. Continuous documentation, command F friendly pages, skeleton generators and search aim to make docs discoverable, trustworthy and easy to maintain.
AI-written summary · about
chapters (10)
- 0:00Start
- 0:56how spotify is making internal documentation better, easier and less boring
- 6:19github in general: plenty of READMES & wikis, yet we fail to maintain them.
- 7:22generally: difficult to get documentation work prioritized
- 19:04two documentation types code system
- 20:16document concepts $ example-cli-tool login "Do you have a EuRuKo code?"
- 20:57document error messages $ example-cli-tool logout "Error 491 unknown error"
- 22:18educate/advocate that great documentation is part of tech health
- 22:34provide tooling for skeleton documentation
- 23:46github workflow integration # open new issue # open new pr
related talks
25mBuilding Docs like Code: Continuous Integration for Documentation
36mBuilding Docs like Code: Continuous Integration for Documentation
43mUseful and Beautiful Developer Docs and How to Create Them
05mDocs as Part of the Product: Open Source Technical Documentation at Scale
45mDocs or it didn't happen!
30mTechnical Documentation
30mBuilding technical documentation as a product at scale
45mDocs as Code Fix a poor documentation culture in your organization