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

Use them if you already have strong adoption, but treat them as the exception—not the default. In practice, docs-as-code wins because it’s versioned with the service, reviewed via PRs, and forced through the same delivery pipeline. If you keep Confluence/Notion, at least link to repo runbooks/ADRs as the source of truth and automate checks so it doesn’t drift.

How do we prevent docs from becoming stale?

Make staleness detectable and owned: `mkdocs build --strict` to catch broken links, `CODEOWNERS` so changes require review, and an incident loop where every Sev1 updates a runbook within 48 hours. Add PR templates and (eventually) CI enforcement for doc updates when operational behavior changes.

What’s the smallest set of documents that moves the needle?

Start with (1) onboarding doc (`README.md` + local run), (2) top 5 runbooks that cover most pages, and (3) ADRs for irreversible decisions (data model, auth, queuing, deployment architecture). Don’t migrate everything—migrate what reduces escalations and MTTR.

How does this help with AI-assisted development and “vibe coding”?

AI-generated code often lacks the why: constraints, trade-offs, and operational implications. ADRs capture the rationale, and runbooks capture how to operate the behavior safely. Combined with ownership and CI, this turns AI speed into something you can actually maintain.

Platform-productivity · Dec 23, 2025 · 8 minute read

The Day the Last Staff Engineer Quit: Rebuilding Institutional Knowledge Without Buying Yet Another Wiki

Institutional expertise leaks out through Slack, tribal memory, and “that one person.” Here’s the paved-road system that keeps knowledge shippable—even when the original authors are long gone.

Back to all posts

The Day the Last Staff Engineer Quit: Rebuilding Institutional Knowledge Without Buying Yet Another Wiki

Key takeaways

Implementation checklist