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
- Deploy TechDocs no matter how your software environment is set up.
- Discover your Service's technical documentation from the Service's page in Backstage Catalog.
- Create documentation-only sites for any purpose by just writing Markdown.
- Explore and take advantage of the large ecosystem of MkDocs plugins to create a rich reading experience.
- Search for and find docs.
- Highlight text and raise an Issue to create feedback loop to drive quality documentation (future).
- Contribute to and deploy from a marketplace of TechDocs widgets (future).
Platforms supported
See TechDocs Architecture to get an overview of where these providers are used.
| Source Code Hosting Provider | Support Status |
|---|---|
| GitHub | Yes ✅ |
| GitHub Enterprise | Yes ✅ |
| Bitbucket | Yes ✅ |
| Azure DevOps | Yes ✅ |
| GitLab | Yes ✅ |
| GitLab Enterprise | Yes ✅ |
| File Storage Provider | Support Status |
|---|---|
| Local Filesystem of Backstage app | Yes ✅ |
| Google Cloud Storage (GCS) | Yes ✅ |
| Amazon Web Services (AWS) S3 | Yes ✅ |
| Azure Blob Storage | Yes ✅ |
| OpenStack Swift | Community ✅ |
Reach out to us if you want to request more platforms.
Project roadmap
Published versions
Alpha release ✅ - Milestone
- Alpha of TechDocs that you can use end to end - and contribute to.
Beta release ✅ - Milestone
- TechDocs' recommended setup supports most environments (CI systems, cloud storage solutions, source control systems).
- Instructions for upgrading from Alpha to Beta
Future work 🔮
General Availability (GA) release - Milestone
- Bugs are rare, TechDocs APIs are stable and scales easily in large organizations.
- Better integration with Scaffolder V2 (e.g. easy to choose and plug documentation template with Software Templates).
- Possible to configure several aspects about TechDocs (e.g. URL, homepage, theme).
Implement Feedback loop - Milestone
- A feedback loop between documentation reader and writer using TechDocs
- The
+indocs-like-code+experience
TechDocs widget framework
Platformize TechDocs with a widget framework so that it is easy for TechDocs contributors to add pieces of functionality and for users to choose which functionalities they want to adopt. As a pre-requisite, the re-architecture of TechDocs frontend RFC needs to be addressed.
Tech stack
| Stack | Location |
|---|---|
| Frontend Plugin | @backstage/plugin-techdocs |
| Backend Plugin | @backstage/plugin-techdocs-backend |
| CLI (for local development and generating docs) | @techdocs/cli |
| Docker Container (for generating docs) | techdocs-container |
Contact us
Reach out to us in the #docs-like-code channel of our
Discord chatroom.