"Document everything" is unrealistic. "Document nothing" is dangerous.
The skill is knowing when documentation is worth the investment.
When to Document
High Stakes
The decision is significant. Getting it wrong is expensive. Others will need to understand it.
Examples: - Architecture decisions - Security-related choices - Compliance-affecting decisions - Expensive-to-reverse commitments
High stakes = document.
Non-Obvious
The reasoning isn't apparent from the result. Future people will ask "why?"
Examples: - Surprising technical choices - Counterintuitive approaches - Trade-offs with invisible costs - Things that "look wrong" but are right
If they'll wonder why, document why.
Foundational
Other things build on this. Misunderstanding cascades.
Examples: - Core architecture - Shared conventions - Integration contracts - Fundamental assumptions
If it's a foundation, document it.
Shared
Multiple people need to understand. Knowledge can't stay in one head.
Examples: - Team-wide decisions - Cross-team interfaces - Standards and conventions - Anything with multiple stakeholders
Shared knowledge = documented knowledge.
When to Ship
Low Stakes
If it's wrong, fixing it is cheap. The cost of documentation exceeds the cost of mistakes.
Examples: - Trivial implementation choices - Easily reversible decisions - Low-impact features
When stakes are low, ship and iterate.
Obvious
The reasoning is self-evident. Nobody will wonder why.
Examples: - Standard patterns - Industry conventions - Self-documenting code
If it's obvious, don't document the obvious.
Experimental
You're trying something. It might not survive. Documentation is wasted on the discarded.
Examples: - Prototypes - Spikes - Early exploration
Experiment first, document what survives.
Solo
You're the only one who needs to know. There's no audience for the documentation.
Examples: - Personal projects - One-off scripts - Throwaway tools
Solo work can stay in your head (with caveats — if it becomes shared, document it).
The Quick Test
Before documenting, ask:
1. Will someone need to understand this later? 2. Is the understanding non-obvious? 3. Will the context be lost without documentation?
If yes to any: document. If no to all: probably skip.
When to Ship Without Documenting
Some situations favor shipping now, documenting later (or never):
**Experiments.** Trying something to see if it works. If it doesn't work, documentation was wasted.
**Trivially reversible.** If you can easily change it later, perfect documentation now is overkill.
**Under time pressure.** Sometimes shipping matters more. Document the most critical pieces; accept gaps elsewhere.
**Solo work that stays solo.** If nobody else will touch it, documentation for others has no audience.
But be honest. "I don't have time" is often "I don't want to." Urgent shipping is real; chronic documentation avoidance is different.
The Middle Path
For most work:
**Before:** Capture intent briefly. Takes 2 minutes.
**During:** Log decisions as they happen. Takes seconds per decision.
**After:** Note outcomes. Takes 2 minutes.
This isn't heavy documentation. It's the minimum that preserves context. The total investment is trivial; the preservation value is high.
Save comprehensive documentation for things that deserve it. Comprehensive for critical systems. Light for everything else.