Somewhere in the middle of every hard debugging session there's a moment where you think: wait, didn't I hit this exact thing last year? You did. You solved it in forty minutes at 11pm, felt like a genius, and wrote it down nowhere. The knowledge lived in your head for about a month, and then rent came due.
A developer journal — the Pragmatic Programmer crowd calls it an engineering daybook — is the cheap fix: a dated log of what you tried, why you tried it, and what actually worked. Not documentation, not a blog. A lab notebook, for code, written for an audience of one future person who will be very grateful.
What goes in (and what doesn't)
- The problem, stated once. Writing “billing job dies only on the 31st” forces the half-formed hypothesis out of your head. Half of rubber-duck debugging is just this.
- Attempts, with reasons. “Trying the timezone theory because the failures cluster at midnight UTC” — so when it fails, you know what was actually ruled out.
- The fix, and why it worked. The line you'll search for next year.
- Anything you looked up twice. The tar flags, the k8s incantation, the API quirk. Looked-up-twice is the journal asking to be fed.
- Decisions and their losers. What you chose, what you rejected, and why — because “why didn't we just use X?” always comes back in six months.
What doesn't go in: standards, formatting, completeness. A daybook with three rough lines beats an empty template with beautiful headings.
The method that survives real weeks
One page per day, timestamps when you switch problems, and no filing — the day is the filing. This is interstitial journaling wearing an engineering hat, and it works for the same reason: each entry costs seconds, so busy days still get written.
In Hejour the shape comes built-in. Every day is a page; a fenced block keeps its syntax highlighting, so the error message and the fix live on the day they happened, readable:
Tag threads with #billing or #incident and ⌘P replays any project's whole history across days. Capture without leaving your editor with ⇧⌘M — or wire it up properly: a git post-commit hook writes every commit message into the day's log, so the journal half-writes itself.
The compound interest
A month in, the journal starts paying twice. Once at debugging time — the “didn't I hit this before?” search now returns an answer. And once at review time: the same dated log of what you shipped and unblocked is the raw material of a brag document, compiled in an afternoon instead of reconstructed from guilt.
Start with today: one line about the thing you're fighting right now. Hejour is a free download — the page for it already exists.