The traditional approach: 1. Build the thing 2. Ship the thing 3. Document the thing
By step 3, context is already fading. You don't remember why you made certain decisions. The details are fuzzy. Documentation becomes reconstruction rather than recording.
The result: thin documentation that captures what but not why. Or no documentation at all because "we'll get to it."
The sequence is backwards.
The Right Sequence
**Before:** Document intent. What are you trying to accomplish? Why? What does success look like?
**During:** Document decisions. What did you decide? Why? What alternatives did you reject?
**After:** Document outcomes. What happened? Did it work? What did you learn?
This sequence captures context when it exists, not after it's gone.
Why Before Matters
Intent documentation before work: - Forces clarity of thought before action - Creates a target to evaluate against - Preserves the "why" that's easy to forget - Provides context for anyone reviewing later
Without intent documentation, you're building toward a vague target and hoping someone remembers why.
Why During Matters
Decision documentation during work: - Captures reasoning while it's fresh - Records alternatives considered (not just path taken) - Creates a trail future developers can follow - Takes seconds when context is live (hours later, if at all)
Decisions made but not documented become mystery. The system has decisions embedded in it. Nobody knows what they were or why.
Why After Matters
Outcome documentation after work: - Records whether intent was achieved - Captures learning for future efforts - Connects evidence to decisions - Completes the story
Without outcome documentation, you never know if your approach worked. You can't learn from experience because experience isn't recorded.
The Practical Implementation
**Before starting:** Take 2 minutes. Write: - What we're trying to accomplish - Why it matters - What success looks like
**During work:** As decisions happen, take 30 seconds: - What was decided - Why
**After completing:** Take 2 minutes. Write: - What happened - Whether it matched intent - What we learned
Total: 5-10 minutes spread across the effort. Context preserved instead of lost.
The Objection
"This slows down shipping."
No. It slows down starting by 2 minutes. It adds seconds during work. It adds 2 minutes at the end.
What slows down shipping is rework because intent was unclear. Debugging because decisions weren't recorded. Onboarding because nothing was documented.
Documentation is investment, not overhead. The return is faster future work, not slower current work.
The Shift
Stop thinking of documentation as something that happens after.
Documentation is part of the work: - Before: clarify - During: record - After: close
The sequence matters. Get it right.