Why not use Docusaurus or a full Backstage portal?

You can, but they’re heavier. MkDocs Material + GitHub Pages is enough to prove the model in a week. Once content and ownership are healthy, you can migrate to Docusaurus or feed Backstage. Content > portal.

How do we keep runbooks from going stale?

Add a “Last Verified” header, a 30-day SLA, and a CI check that fails PRs if the date is too old for Tier 1 services. Tie postmortems to runbook updates.

Who owns the org handbook?

Platform or DevEx owns the repo and CI. Each domain section has CODEOWNERS for review. The goal is distributed ownership with a paved road, not central gatekeeping.

What about sensitive content (secrets, IP)?

Docs live with code, so use the same controls: repo permissions, secret scanners, and no secrets-in-docs. For truly sensitive runbooks, keep them in private repos and link from the handbook with access controls.

Can we plug this into AI assistants later?

Yes—this is the right corpus: clean Markdown with ownership and recency metadata. You can index it with embeddings, add `last_verified` frontmatter, and build RAG with confidence. Don’t start with AI; earn it.

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

The Day Your Staff Engineer Walks: A Paved‑Road Knowledge System That Keeps Shipping

Stop treating knowledge as a side project. Make it a first-class, versioned dependency that survives reorgs, layoffs, and hero departures.

Back to all posts

The Day Your Staff Engineer Walks: A Paved‑Road Knowledge System That Keeps Shipping

Key takeaways

Implementation checklist