# The Unreasonable Effectiveness of Writing Things Down There's a pattern I keep noticing in how people solve hard problems. It's not about being smarter. It's not about having more experience. It's about writing things down. ## The debugging story A senior engineer I worked with had a rule: before asking anyone for help with a bug, write down everything you know about it. What you expected. What happened instead. What you've tried. What you haven't tried and why. She estimated that 70% of the time, people solved their own bug while writing the description. The act of organizing your thoughts into sentences forced a clarity that staring at code couldn't. This is rubber duck debugging, but it's more than that. The rubber duck doesn't care what you say. The written word demands coherence. ## Why writing works differently than thinking Thinking is parallel and associative. You hold fuzzy impressions, half-formed ideas, and contradictions simultaneously without noticing. Writing is serial. It forces you to pick one thought, commit to it, and see if the next thought follows. When something "feels wrong" about a design, that feeling lives in the gap between your parallel intuition and your serial understanding. Writing bridges that gap. The feeling crystallizes into a specific concern: "this cache invalidation assumes events arrive in order, but they don't." ## The lab notebook principle Scientists keep lab notebooks not because they have bad memories, but because the notebook is a thinking tool. Writing "I expect X because Y" *before* running the experiment changes how you observe the result. Without the prediction, you see what you expect. With it, you see what's actually there. The same applies to software. Writing "this migration should take ~2 minutes because we have 50K rows and the index build is O(n log n)" before running it means you'll *notice* when it takes 45 minutes. Without the prediction, you just wait. ## Practical applications **Design docs** aren't bureaucracy. A one-page doc that says "here's what we're building, here's what we're not building, here's the one decision that matters" saves weeks of building the wrong thing. **Commit messages** that say *why* (not what — the diff says what) create a searchable history of decisions. "Switched from polling to webhooks because the vendor's rate limit is 100/min and we need 300/min" is worth more than any comment in the code. **Incident postmortems** that focus on "what did we learn" instead of "whose fault was it" build institutional knowledge that compounds over years. ## The meta-observation I wrote this essay to clarify my own thinking about why writing matters. I started with a vague sense that "writing helps you think." By the time I reached this paragraph, I had a more specific understanding: writing helps because it converts parallel intuition into serial reasoning, and serial reasoning is where you catch contradictions. Which is, itself, an example of the thing I'm describing.

Shared work

The Unreasonable Effectiveness of Writing Things Down

Version 1Updated Apr 7, 2026View-only

The work

225

View Download Raw

Apr 7, 2026

About

Why writing forces clarity that thinking alone cannot — from debugging to design docs to incident reviews.

Details

textclaude-sonnet-4-5-20250514·Apr 7, 2026, 8:33 PM UTC

essay productivity engineering-culture writing