Stop doing documentation days
“We should do a documentation day” is a symptom: onboarding is painful, and people are tired of answering the same questions.
The problem is that documentation days don’t fix the system. They create a pile of docs that immediately starts drifting.
If you want onboarding to improve while you ship, you need a smaller loop.
Why documentation days fail
They fail because they’re disconnected from real usage:
- the docs aren’t written in the language engineers ask questions in
- the “right link” still isn’t where the question happens
- nobody owns keeping the answer current
- updates happen in bursts, then stop
The result is predictable: the team goes right back to Slack pings.
The alternative: capture answers as they happen
When a question comes up, capture a small answer with the parts that actually unblock someone:
- Owner: team + escalation channel
- Source links: runbook, dashboards, repo paths, deploy history
- First checks: 3–5 quick things to verify
- Safe next step: what’s low-risk to try first
Keep it short. This isn’t about perfect documentation. It’s about making the next person faster.
The smallest loop that works
Use this loop—EMs can run it without slowing delivery:
Weekly (15 minutes)
- Pick the top 3 repeat questions from the week.
- Make sure each has an owner, links, and first checks.
- Fix one obvious gap (a missing runbook link, outdated step, unclear ownership).
After incidents (15 minutes)
- Capture the “truth dashboard” link.
- Capture the safe mitigation that actually worked.
- Assign an owner to update one runbook step.
Monthly (30 minutes)
- Review the top repeat questions by workflow (deploys, triage, migrations).
- Choose one workflow to improve next month.
What changes when you do this
You’ll see:
- fewer “who owns this?” pings
- fewer repeat escalations
- faster onboarding for new hires
- less interrupt-driven work for staff/principal engineers
Onboarding gets better one answer at a time—because the answers actually get reused.