Should we use Confluence instead of docs-as-code?

If Confluence is already working for you and people keep it current, fine. The failure mode I’ve seen is “docs live somewhere separate from code,” so they drift. Docs-as-code wins because it shares the PR workflow, review gates, and ownership model. You can still publish the rendered site for non-engineers.

When do we need a service catalog like Backstage?

When you have enough services that humans can’t keep the map in their heads (usually dozens+) and you need standardized metadata (ownership, tiers, dependencies). Start by creating `service.yaml` files and enforcing the “no orphan services” rule. You can adopt Backstage later and ingest the same metadata.

How do we stop runbooks from becoming outdated?

Tie them to change workflows: PR templates that ask about ops impact, `CODEOWNERS` so the right team reviews updates, and CI checks (broken links, required files present). Also, review runbooks during postmortems: every incident should produce at least one concrete runbook improvement.

Platform-productivity · Jan 18, 2026 · 8 minute read

The Staff Engineer Quit and Took the Map With Them: Building Knowledge Systems That Survive Turnover

Institutional expertise isn’t a wiki problem — it’s a workflow problem. Here’s the paved-road setup that keeps tribal knowledge from walking out the door.

Back to all posts

The Staff Engineer Quit and Took the Map With Them: Building Knowledge Systems That Survive Turnover

Key takeaways

Implementation checklist