Why not just standardize on Confluence or Notion?

They’re fine for PM specs and long-form narratives, but they live outside the flow of engineering work. Without CI checks, CODEOWNERS, and proximity to code changes, drift is inevitable. We keep wikis for narratives, but the source of truth for runbooks, ADRs, and API docs sits in Git with automation.

Do we need Backstage?

Not always. If you’re small, a thin internal directory (even a static site generated from repo metadata) works. At ~10+ teams, Backstage as a simple catalog pays off. Start with identity and catalog only; avoid plugin sprawl until adoption is real.

How do we keep docs fresh without killing velocity?

Automate freshness checks, keep docs short and local to code, and make updates part of PRs. The time you ‘lose’ writing the runbook is gained back many times during incidents and onboarding. Treat freshness like an SLO, not a suggestion.

What about regulated environments?

Git-native docs improve traceability. Every change is versioned, reviewed, and linked to tickets. You can snapshot docs at release tags for audits. We’ve shipped this in PCI and HIPAA shops by adding retention and approval workflows in GitHub/GitLab.

Can AI write our docs?

It can draft and summarize, but it shouldn’t be the source. Use AI to propose runbook steps, extract API descriptions from code comments, or answer Slack questions by pointing to Git URLs. Humans own accuracy; Git owns truth.

Platform-productivity · Oct 1, 2025 · 9 minute read

The Day Your Principal Walked and Your SRE Playbook Went With Them

Tribal knowledge doesn’t scale. Paved-road docs, service catalogs, and lightweight decision records do.

Back to all posts

The Day Your Principal Walked and Your SRE Playbook Went With Them

Key takeaways

Implementation checklist