What about teams that hate writing docs?

Pair write during incident reviews and design reviews. Keep docs short, procedural, and close to code. Reward links in PRs.

Can we do this on GitLab/Bitbucket?

Yes. Use GitLab Pages/CI or Bitbucket Pipelines plus a static hosting bucket. Same pattern and principles.

How do we handle secrets in runbooks?

Never inline secrets. Reference commands like aws ssm get-parameter or vault kv get, and link to access controls with least privilege.

What if we already invested in Backstage?

Keep it, but feed it from the same Markdown sources. Don’t fork the truth. Backstage can render or link to the docs; the source of truth remains Markdown in repos.

How do we avoid stale ADRs?

Treat ADRs like code: PRs, reviews, and deprecations. Add a linter that checks Status and Last Reviewed date; include ADR updates in change PRs.

Platform-productivity · Oct 18, 2025 · 10 minute read

Slack Is Not a Knowledge Base: Build a Paved Road That Survives Reorgs

If your production runbooks live in someone’s head (or a Slack DM), you’re one departure away from a very expensive incident. Here’s the simple, boring, and durable system that actually preserves institutional knowledge.

Alex Mercer

Principal Consultant, GitPlumbers

Twenty years in the trenches across fintech, SaaS, and infra. Ex-SRE manager, platform lead, and recovery specialist for systems that paged too much and shipped too little.

Boring, paved roads beat bespoke portals every quarter and twice on incident nights.

Back to all posts

Slack Is Not a Knowledge Base: Build a Paved Road That Survives Reorgs

Key takeaways

Implementation checklist