Principle: Aggressive. DRY. KISS.
Document everything you do. Say it once. Say it simply.
- Does this already exist somewhere? Search first - don't create a second source of truth.
- If it exists but is wrong/outdated, fix it there instead of writing a new doc.
- If it doesn't exist, write it now - not "later." Later is where documentation goes to die.
- State each fact, decision, or config value in exactly one place.
- If you need to reference it elsewhere, link to it - don't restate it.
- A short pointer line before a link is fine ("see X for setup steps"). Re-explaining X is not.
- If you're pasting the same paragraph into a second doc, stop - that paragraph should live in one place and be linked from both.
- Cut anything obvious to your intended reader.
- One idea per sentence. One topic per paragraph.
- No hedging, no throat-clearing, no "as you may know."
- No speculative edge cases nobody has hit yet - add them when they happen.
- Could a teammate skim this in 30 seconds and know what to do? If not, cut more.
- Did you write this down at all, or is it still just in your head / a Slack thread?
- Is it findable? (right folder/repo, linked from wherever someone would look first)
- Did you link out to related docs instead of duplicating their content?
- Would a new hire understand this without asking you directly?
| Ask yourself | If yes |
|---|---|
| Am I about to explain something twice? | Delete one, link instead |
| Am I about to explain something obvious? | Delete it |
| Am I skipping this because it feels like too much effort? | That's the aggressive part talking you out of it - write it anyway |