For years I solved the same problems twice. Not because they were hard, but because I'd forgotten how I solved them the first time. Writing notes fixed that — and, unexpectedly, made me a clearer engineer.
Notes are for future you#
The audience of a work note isn't the internet. It's you, six months from now, at 11pm, staring at the same stack trace. Write for that person: what broke, what you tried, what actually worked, and why.
A format small enough to keep#
Every note I write fits in four headings. If it takes longer than ten minutes, it's probably an article, not a note.
- Context — one or two sentences about the situation.
- Problem — the symptom, exactly as it appeared.
- What worked — the fix, with a snippet or link.
- Why — the mechanism. This is the part you'll thank yourself for.
From notes to articles#
Most posts on this blog started as a handful of notes that kept pointing at the same idea. When three notes share a "why", that's a topic worth writing up properly.
You don't really understand something until you can explain the trade-off, not just the fix.
Learning in public, gently#
Publishing doesn't have to be loud. Share the notes that might save someone an afternoon, admit what you're still unsure about, and update posts when you learn more. Being honest about uncertainty is a feature, not a weakness.
- Write the note while the problem is still fresh.
- Keep the "why" even if the fix is one line.
- Link related notes to each other.
- Revisit monthly and promote recurring themes to articles.