Week 7: On Writing Better Docs
This week I rewrote our team’s onboarding docs. They were outdated, scattered across 4 different wikis, and nobody read them.
The problem with most docs
They’re written for the wrong audience. Engineers write docs like they write code:
- Comprehensive
- Technically accurate
- Organized by system architecture
But readers want:
- Quick answers
- Practical examples
- Organized by their goals
What worked
- Start with the happy path: One clear example that works end-to-end
- Add troubleshooting: Common errors and how to fix them
- Link to depth: Reference docs for those who need details
- Keep it short: If it’s longer than 2 pages, split it
The result
New engineers now go from laptop to first PR in 2 hours instead of 2 days.
That’s 12 hours saved per engineer. We hire 2 engineers per month. That’s 24 hours per month or 288 hours per year.
Good docs are a force multiplier.
Action item
Find one piece of documentation that’s blocking your team. Rewrite it this week.