The decision log

There is one habit that has given me more than any tool, and it costs ten minutes a week: writing down what I decided, why, what I rejected and what would change my mind.

It sounds like paperwork and it is the opposite. Paperwork is writing so that it is on record. This is writing so that you can come back.

What exactly goes in

Four things, none longer than two sentences. The decision. The reason, while it was still fresh. The alternatives I rejected, which is the part everybody forgets. And what would have to happen for me to change my mind.

The fourth is the most useful and the one fewest people write. It is what turns a decision into something reviewable: if six months pass and that condition has been met, you have an objective reason to reopen the subject rather than a feeling.

What it is really for

The obvious use is not repeating arguments. But the one that has served me most is a different one: telling a bad decision apart from a bad outcome.

They are not the same. You can decide well with the information you had and still have it go badly, and you can decide terribly and get lucky. If all you remember is the outcome, you will learn the wrong lesson both times. The record of why you decided what you decided is the only thing that separates them.

The second use shows up once other people are involved. While you are the only one who knows why each thing is the way it is, you do not have a system: you depend on being available. And that holds up perfectly until the day you are not.

How I do it

Plain text, one file, chronological, no structure. I have tried tools with templates and fields and I always abandon them, because the cost of filling in the form is higher than the benefit felt at that moment.

A file you open and write in survives. A system that has to be maintained does not. And I only log decisions that would be expensive to undo: if it is reversible and cheap, it does not earn an entry.

What not to do

Do not turn it into a diary. The moment you start recounting how the week went, it stops being consulted, and a log nobody consults is wasted time with a clear conscience.

And do not write it after you know the outcome. A decision recorded afterwards always looks more sensible than it was, because your head has already rearranged the reasons to fit what happened.

Questions people ask about this

How is this different from an ADR?

An architecture decision record is the same thing applied to technical decisions with more formality. The idea is identical; what I do is the light version applied to product, with no template and no peer review.

Which decisions are worth logging?

The ones that would be expensive to undo. A pricing change, choosing a platform, ruling out a type of user, changing direction. Do not log the reversible and cheap ones: you will get tired and drop the habit.

Is it useful if I work alone?

Especially if you work alone. It is the closest thing to having somebody ask why you are doing that, except the person asking is you a few weeks later.