The question you don't dare ask out loud
It's 10:40 PM on a Tuesday, I just closed an ADR — the seventy-fourth in this setup, written conscientiously, dated, cross-referenced with its migration, its contract test, and the commit that triggered it. And the question rises, the way it always rises at that hour when you've been coding alone for ten hours: who did I just write this for. No tech lead to convince, no PR review that'll catch it, no hypothetical acquirer to reassure, no architecture committee to brief tomorrow. Just the file, just me, just the doubt.
It's the question of a solo dev at 70 days of serious practice. It has an honest answer, and that answer is neither "it'll pay when you sell" nor "it'll pay when you hire". Those two ROIs belong to other trajectories. The ROI of the solo dev who documents is an ROI he buys himself — deferred, intangible at moments, but materially countable if you force yourself to measure it in the first person. Here's mine, over 74 ADRs and 18 doctrine rules accumulated in 70 days, with no external observer to validate the grid.
The false economy of "I'll remember"
First trap, the one that cost me three weeks before I learned the lesson. The solo dev believes he doesn't need to write down what he decided because he decided it himself — his memory is worth an ADR. False at 14 days, systematically false at six weeks. Not because general memory fails, but because technical memory has a deceptive shape: you remember perfectly that you decided, you no longer remember why you decided that way.
Three weeks after the May 5 session where I wrote ADR-0051 (FK ON DELETE SET NULL + CHECK NOT NULL incompatible, DELETE failing silently), I reopen the migration to add a column. I reread the diff, I don't understand why a certain CHECK constraint is phrased like this — the alternative I mentally dismiss today seems simpler, and I'm two clicks from refactoring. I go check the ADR. The answer is there, dated, sourced, in three lines. The simple alternative is exactly the one I explored and abandoned because of an edge case I've since forgotten. Without the ADR, I would have redone it. Probably two hours of re-decision, plus the silent incident my code would have re-produced six months later.
The ADR isn't an audit deliverable. It's a note you mail yourself with delayed delivery. The beneficiary is in the same chair, just at another moment in time.
The first-person measurable ROI
Over 70 days, I can count three things.
Re-decision time saved. About fifteen times, I went back to consult an ADR instead of redeciding. Each time, twenty to forty minutes saved on the cognitive diff of a silent re-argument with myself — the one where you reread the code, imagine alternatives, wonder if you hadn't picked the wrong option. The ADR cuts it short: the wrong option has already been examined, here's why it loses, move on. Twenty minutes × fifteen ≈ five hours recovered over 70 days. Not billable time as a consultant would measure it — time I didn't spend doubting, and that I spent shipping.
Fix-rollback cycles avoided. The falsify before fix protocol — formulate a causal hypothesis then execute three probes designed to refute it — saved me, over the same period, seven well-identified fix-then-rollback cycles (the sessions where the term appears explicitly, conservative count). Each cycle is five to ten minutes of upstream protocol against thirty to ninety minutes of a fix that doesn't fix, followed by rollback and restart. The ratio computes without optimism: six to eighteen times the invested time, per incident where the protocol held. For a solo dev, this isn't a productivity economy in the team sense — it's a morale economy, not refacturable but deciding whether I'm still coding at 6 PM or whether I silently stopped at 4 PM without telling anyone.
Silent drifts detected. The pattern one confirmed case, grep the complete pattern — every time a bug is reported on a precise case, widen before fixing — made me go several times from an isolated report to an audit that surfaced four, sixteen, sometimes five hundred lines affected by the same root cause. It's not the ADR that runs the grep, but it's the doctrine that lays down the reflex and the ADR that codifies it so that my three-weeks-from-now self doesn't forget. The real ROI measure isn't the number of cases found, it's the ratio between what I'd have seen without the rule (one case, the visible) and what I saw with it (the entire class, the invisible).
What it doesn't pay
Brutal honesty. ADR discipline doesn't pay prototyping speed — when I want to try a wild idea on a Saturday morning, I don't write an ADR, I write code tagged [spike] that will be deleted within seven days, and I'm better off for it. It doesn't pay existential doubt — the ADR confirms I decided well, it doesn't tell me whether I decided well about the right problem, and that's a question of another order that the doctrine doesn't touch. It doesn't pay marketing, doesn't pay team cohesion (no team), doesn't pay commercial prospecting.
The trap I also see, and that I flag because it concerns me directly, is the solo dev who starts documenting because documenting reassures, and ends up documenting instead of shipping. The doctrine becomes a burrow. At 70 days, I hold the ratio — one ADR for what is decided and durable, not for what is explored. My current ratio runs at 1.7 ADRs per active session, and that's precisely the threshold at which I start looking at myself sideways. Above two per session, I'd probably be hiding from code behind the doctrine. It's a warning signal nobody else can give me.
The invisible ROI
There remains the axis no external observer could code into a metric, and it's probably the one that weighs most for solo practice.
Confidence in your own system. Being able to reopen a module you haven't touched in six weeks, read the three ADRs that describe it, and resume the modification without having to re-read everything line by line. The cognitive calm of a system that doesn't ask to be re-understood, that hands you its reasons and lets you continue. That's what a solo founder needs to not crack at month 4 — not a productivity metric, a holding-in-time metric. Nobody sold it to me at the start of the journey because nobody sells it; you discover it retrospectively, when you realise you haven't panicked once this month, and you wonder why.
That's probably the only honest answer to the 10:40 PM question. The ADR will not pay the hire, nor the client, nor the valuation. It will pay my ability to keep coding this system three months from now without hating it. It's an ROI no investor will value, and that's nevertheless the only one that concerns me.
Coda
If you're hesitating to write yours because you tell yourself no one will read it, write it anyway. The reader is you in three weeks. He'll need it. That's exactly that, and nothing else.
Solo dev, 74 ADRs in 70 days, no team, no PR review. The honest balance — measured from the only seat that matters: mine.
Top comments (0)