Why I Write Things Down

I keep a plain-text file for every project I start. It’s called notes.md, it lives at the root of the repository, and it has no structure to speak of. Sometimes it’s a scratchpad. Sometimes it’s a diary. Occasionally it’s a place where I talk myself out of a bad idea in writing.

This is the single most useful habit I have, and it took me ten years to acquire it.

Memory is a terrible database

Software projects are not failed by their complexity. They’re failed by the forgetting. The decision you made in March, and the reason you made it, and the constraint that made it seem reasonable — by November, none of that survives in your head. What survives is a vague feeling that the current code is wrong somehow, which is worse than knowing nothing, because it produces arguments instead of understanding.

When I write decisions down as I make them, the future-me stops re-litigating. The question “why is this like this” has an answer that takes thirty seconds to find instead of a week of archaeology.

Writing is thinking

The more honest version of the argument is that I don’t write because I have thoughts. I write because I don’t, and writing is the fastest way to find out.

A problem that seems impossibly tangled in the shower becomes tractable at a keyboard, not because the keyboard is magical, but because prose forces linearity. It forces you to commit. The sentence that won’t end cleanly is usually the sentence that contains the flaw — the one that says we should probably handle the offline case when you don’t actually know how.

Code does this too, but slowly and expensively. Prose fails fast. I’d rather have a paragraph embarrass me than a production incident.

What I actually keep

Not a diary, and not a blog. Three kinds of things:

1. Decisions and their reasons. One or two sentences at the time of choosing. Future-proofing.
2. The shape of the problem. Not the solution — the shape. “We’re optimizing for cold start at the expense of streaming.” Half a paragraph.
3. What I’d do differently. Written the week the thing ships, while the scar is fresh.

That’s it. No templates, no apps, no folders of system. The constraint is low friction — if keeping the note takes more than five seconds, I’ll stop doing it. So it’s always a file, always at the root, always ugly.

The byproduct

The strange thing is what the notes turned into. After years of writing bad, honest notes to myself, I started editing them into essays, and the essays started teaching people things I didn’t know I knew. The blog on this site is mostly recycled scratchpad.

The habit stopped being about remembering and became about understanding. Which, it turns out, is what writing has always been for — a technology for thinking, available to anyone with a keyboard and an afternoon.

I write things down because I want to think, and I want to think because there’s no version of the work I care about that doesn’t require it.