ADHD Diary #009: The Documentation Debt That Won't Pay Itself

I just opened a folder on my laptop and counted. 23 markdown files with titles that include some variant of "FINAL", "v2", "actually_final", "FINAL_USE_THIS_ONE", and one called "FINAL_v3_DELETE_OTHERS_THIS_IS_REAL". They are all unread by anyone except me. They were all written with the intention of being documentation. None of them is.

This is the standing pattern of my life as a builder with ADHD. I generate intentions to document. The documentation almost happens. Then a different task wins the dopamine race and the half-written file sits in the folder, accruing significance only by virtue of having a filename that promised more than its contents delivered.

The shape of documentation debt

Documentation debt is technical debt that nobody capitalises. You can't see it on a balance sheet, can't measure it cleanly in tests, can't even point at it the way you can point at a slow query or a memory leak. It exists in the negative space — in the time future-you spends re-deriving what current-you already figured out and didn't write down.

For ADHD brains, this debt accumulates faster than for neurotypical brains. The discharge mechanism is also different. Standard productivity advice ("just block out an hour to document") assumes a brain that can sit through an hour of low-stimulation transcription. My brain treats that hour the way most brains treat eating a salad while watching paint dry.

So the debt compounds. And every quarter I look at the folder, count the half-finished docs, and tell myself I'll catch up. I don't catch up. I refinance.

What I've tried that didn't work

The standard tools-and-techniques list:

Notion templates. I built three. They are beautiful. I haven't filled one out in a year. The friction of opening Notion, finding the right template, and starting to type is enough that the documentation never starts.

Forcing function: documentation-as-DoD. Adding documentation as part of "done" for any feature. This works for about two weeks, then the documentation step gets deferred to a "later" that never arrives.

Document-as-you-go. Writing the documentation in parallel with the code. This requires sustained attention to two threads simultaneously, which is exactly the thing my brain doesn't do.

Pair documentation. Pairing with a teammate where one writes code and the other writes docs. Works briefly. Decays when schedule pressure hits and the second person gets pulled to other work.

Documentation Fridays. A weekly cadence with explicit time blocked. Lasted six weeks the first time. Three the second. Two the third.

The pattern is clear: anything that requires sustained attention to documentation as a separate activity from the work doesn't survive contact with the unpredictable shape of an ADHD week.

The hack that's been working for nine months

I started in October 2025 and the discipline is still holding. It's stupid. It works.

Voice memo while doing the work. I have a Bluetooth earbud and a transcription tool. When I'm in the middle of building something — debugging, deploying, architecting — I narrate what I'm doing into the earbud. Not "writing documentation". Just talking through the decision as if explaining it to a future engineer.

The transcript gets dumped into a markdown file at the end of the session, automatically. The file has timestamps, my actual voice, the rationale at the moment the decision was made.

Future-me reads this. The transcript is not polished documentation — it's a verbal stream-of-consciousness with all the "ums" and "actually let me try this instead" moments left in. That's the point. The decision context is preserved.

When the same project comes back to my desk three months later and I'm trying to remember why I wrote it the way I did, I open the transcript and the answer is there, in my own voice, from the moment I made the call.

Why this works when other approaches don't

Three reasons, I think.

The friction is zero. I'm already talking through decisions to myself anyway — most ADHD builders do, because verbalising helps with focus. The transcription just captures what was already happening.

It doesn't require a separate "documentation" mode. The documentation is a side effect of the work, not a distinct activity. There's no context switch. The dopamine cost of switching modes — which is what kills every other approach — isn't paid.

The output is good-enough rather than good. The transcript is messy, conversational, sometimes embarrassing to read back. But it's accurate and complete in a way polished documentation rarely is. The trade-off is the right one for the problem.

What this doesn't fix

Three caveats, in the spirit of being honest.

It doesn't produce documentation that other people can use. The transcript is for future-me. Sharing it with a teammate is awkward (they have to listen to me talk to myself for ten minutes). For team documentation, I still owe the polishing step, and that step still doesn't happen reliably.

It generates a backlog of unedited transcripts. I have 200+ hours of project-narration sitting in a folder. Indexing it is its own problem. Search-by-keyword works but isn't great. I haven't built the tooling to make this scale beyond solo use.

It doesn't compose into onboarding material. A new engineer joining a project doesn't want to listen to my decision-monologues. They want a 30-minute orientation document. I still owe that. It still doesn't get written.

For a one-person research project or a solo build, the voice-memo approach has worked. For a team that needs to onboard new members or hand work to other engineers, it's necessary but not sufficient.

Where I still fail

This week, three projects' worth of decisions sat un-narrated because I forgot to put the earbud on before starting. The discipline of remembering to start the tool is itself a tax. Some days I pay it. Some days I don't.

The 23 markdown files in the FINAL folder are still there. None of them have been updated in three months. The voice memos for those projects exist for the last nine months. The first fourteen months of the project are gone — both from documentation and from memory.

That's the honest version. The hack works prospectively. It can't recover the past. The documentation debt for everything before October 2025 is still on the books, and it's not getting paid down.

I'll probably write the same diary entry again in twelve months with different numbers.