Why not just use Confluence/Notion?

They’re fine for product specs and general notes. But engineering knowledge decays unless it travels with code. Docs-as-code keeps changes reviewable, versioned, and enforced via CI. Use Confluence/Notion for planning; keep runbooks/ADRs in the repo.

What if we already invested in Docusaurus or another site generator?

Keep it. The critical piece is paved-road conventions: folders, templates, owners, CI rules, and discoverability. Swapping MkDocs for Docusaurus won’t change outcomes if you keep the same defaults.

How do we stop AI hallucinations from polluting docs?

Treat AI as a drafting tool. Require owner approval for AI-suggested changes, anchor summaries to cited sources (links to ADRs, runbooks), and block merges that add facts without references. Measure drift by link checks and on-call verifications.

Is Backstage required?

No. It’s a nice front door, but you can start with a simple `services.md` index and shortlinks. The win comes from linking service → owner → runbook → dashboard, not from the UI you pick.

What business impact should we expect?

Within a quarter: faster onboarding (30–60% improvement), MTTR down 25–60%, fewer pager escalations, and less attrition from tribal-knowledge fatigue. The cost is a week of setup and ongoing light-touch hygiene.

Platform-productivity · Nov 15, 2025 · 10 minute read

The On‑Call That Exposed Our Bus Factor: Shipping a Paved‑Road Knowledge System in 90 Days

Your tools aren’t the problem—your lack of a paved road for knowledge is. Here’s how to capture institutional expertise without building a bespoke Rube Goldberg machine.

Back to all posts

The On‑Call That Exposed Our Bus Factor: Shipping a Paved‑Road Knowledge System in 90 Days

Key takeaways

Implementation checklist