The Documentation Graveyard Problem
Every engineering organization has a Confluence wiki that is 60% outdated, 30% duplicated, and 10% actually useful. Documentation written separately from code decays the moment it is written. The service changes; the wiki page does not. New engineers read the wiki, follow the instructions, and hit errors that were fixed six months ago.
The root cause is separation of ownership. The code lives in Git, versioned and reviewed. The docs live in Confluence, unversioned and forgotten.
The "Docs Like Code" Philosophy
The fourth pillar of Backstage is TechDocs, built on the philosophy of "Docs as Code." Documentation should be:
- Written in Markdown files.
- Stored in the same Git repository as the source code.
- Version controlled — every doc change goes through a pull request.
- Automatically built and published to the portal on merge.
How TechDocs Works End-to-End
- A developer writes
docs/index.md(and other Markdown files) in their service's repository. - A
mkdocs.ymlfile in the repo root configures the documentation structure. - The CI pipeline runs
techdocs-cli generateto build a static documentation site from the Markdown files. - The generated site is published to object storage (e.g., an S3 bucket or GCS bucket).
- When a developer opens the service's page in Backstage, TechDocs fetches and renders the documentation directly in the portal.
A minimal mkdocs.yml for TechDocs looks like this:
site_name: Payments API
site_description: Documentation for the payments-api service
nav:
- Home: index.md
- Architecture: architecture.md
- Runbooks:
- Restart Procedure: runbooks/restart.md
- Database Failover: runbooks/db-failover.md
plugins:
- techdocs-core
The result: when a developer searches the Catalog for payments-api, they see its documentation right there — and because the docs live in the same repo as the code, a pull request that changes behavior should also update the docs. Code review enforces documentation quality.
Interviewers building platform teams often ask: "How do you keep documentation accurate at scale?" The TechDocs answer is: co-locate docs with code so they share the same review and merge lifecycle. But go further — mention that you can enforce documentation presence with CI checks (fail the build if docs/index.md is missing) and use the Backstage catalog's techdocs-ref annotation to link a service to its docs location. This shows you understand both the tooling and the cultural enforcement mechanism.