TechDocs Documentation
What is it?
TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage. This means engineers write their documentation in Markdown files which live together with their code.
Today, it is one of the core products in Spotify’s developer experience offering with 2,400+ documentation sites and 1,000+ engineers using it daily. Read more about TechDocs and the philosophy in its announcement blog post. 🎉
Features
A centralized place to discover and read documentation.
A clear end-to-end docs-like-code solution.
A tightly coupled feedback loop with the developer workflow. (Coming soon in V.3)
A developer ecosystem for creating extensions. (Coming soon in V.3)
Project roadmap
| Version | Description |
|---|---|
| TechDocs V.0 ✅ | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. See V.0 Use Cases. |
| TechDocs V.1 ✅ | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. See V.1 Use Cases. |
| TechDocs V.2 🔮⌛ | Platform stability and compatibility improvements. See V.2 Use Cases. |
| TechDocs V.3 🔮⌛ | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features. |
Use Cases
TechDocs V.0
- As a user I can navigate to a manually curated docs explore page.
- As a user I can navigate to and read mock documentation that is manually uploaded by the TechDocs core team.
TechDocs V.1
- As a user I can run TechDocs locally and read documentation.
- As a user I can create a docs folder in my entity project and add a reference
in the entity configuration file (of the owning entity) to my documentation.
- Backstage will automatically build my documentation and serve it in TechDocs.
- Documentation will be displayed under the docs tab in the service catalog.
- As a user I can create a docs only repository that will be standalone from any other service.
- As a user I can choose my own storage solution for the documentation (as example GCS/AWS/Azure etc)
- As a user I can define my own API to interface my own documentation solution.
TechDocs V.2
Platform stability and compatibility improvements
- As a user I can define the metadata generated for my documentation.
- As a user I will be able to browse metadata from within my documentation in Backstage.
TechDocs V.3
more to come...
Structure
Tech Stack
| Stack | Location |
|---|---|
| Frontend | @backstage/plugin-techdocs |
| Backend | @backstage/plugin-techdocs-backend |
| Docker Container (for generating doc sites) | packages/techdocs-container |
| CLI (for local development) | packages/techdocs-cli |