What I write down, and why

Why any of this exists

I have mostly worked without a colleague. No reviewer, no second opinion, and no shared memory of why something is the way it is.

The last of those is the one that surprised me. Working alone, the person who will not remember why a decision was made is not a hypothetical successor. It is me, in about four months, with total confidence and no recollection.

So I write two documents. They do different jobs and mixing them makes both worse.

The plan, while the work is in flight

Not a specification. A living record of what is being built, in what order, and where it actually is.

Three properties matter.

It is edited as reality lands. A plan that describes what I hoped in week one is fiction by week three. When something turns out differently, the plan changes to say so. The value is entirely in it being current, and a plan nobody updates is worse than none because it is confidently misleading.

It records what is done, not what is intended. There is a real difference between “build the scheduler” and “the scheduler is built and proven, the promotion sweep is built and not yet proven”. The second tells me where to resume.

It is the source of truth for state. If the plan and my memory disagree, the plan wins. This sounds like a small rule and it is the one that makes stopping for two weeks survivable, which happens constantly.

The practical test: could I be interrupted for a month and resume from this document without reconstructing anything. That is the standard, and it is not met by a list of tasks.

The handoff, once it ships

A different document with a different job. Not documentation of the code, which the code already provides better than prose can.

What goes in it:

The decisions and their reasoning. What was chosen, what was rejected, and what it cost. The reasoning is what cannot be recovered from the code, because code shows what was decided and never why.

What surprised me. The behaviour I did not expect. The library that does not do what its documentation implies. The thing that was three times harder than estimated, and specifically why.

What I tried that did not work. The most valuable section, and the one most often left out. Without it I re-attempt approaches I have already disproved, which I have done, more than once, several months apart, with the same conclusion.

The traps. Things that look safe and are not. A migration that rewrites a table. A helper with a non obvious precondition. The order two things have to happen in.

How it is verified. Not the test suite, which is discoverable. The manual checks, the reconciliation queries, the thing to look at after a deploy to know it worked.

Why the failed approaches section earns its place

It is the most useful thing I write and it feels the least useful while writing it.

Writing down what worked feels like recording progress. Writing down what did not feels like recording failure, and there is a small ego cost to it.

But the code contains the successful approach already. It does not contain the four hours spent on something reasonable that turned out not to work, and that is exactly the trap the next reader will fall into, because it was reasonable, which is why I tried it.

What I do not write down

Worth stating, because the failure mode of this habit is documenting everything and therefore maintaining nothing.

Not what the code does. It is there, it is accurate, and prose about it goes stale immediately.

Not API documentation that could be generated. Generate it.

Not process for its own sake. A document nobody reads, including me, is a cost with no benefit.

The test I apply: would somebody be worse off without this in six months? If not, it does not get written.

The unexpected effect on decisions

Writing the reasoning down at the time changes the decisions themselves.

An argument that is convincing in my head is frequently unconvincing on the page. Several times I have started writing why I chose something, found the justification thinner than it felt, and changed the choice.

That is the closest thing to a code review I have available working alone, and it catches maybe half of what a colleague would. Not because writing is magic, but because it forces the argument to be explicit, and most weak arguments survive on being implicit.

What happens on a team

This is the part I would want a hiring manager to take from it.

The habit was built out of necessity, and it turns out to be simply good practice with the constraint removed. Written plans mean anybody can see where work stands without asking. Handoffs mean work can be picked up without a meeting. Recorded decisions mean the same argument is not relitigated every quarter by people with no memory of why it was settled.

None of it was designed to make me a better colleague. It happens to, which I did not expect.