On keeping a changelog for yourself

Software ships with release notes. People rarely do. A small practice for noticing that you have, in fact, changed.

Rafael Ortiz

Rafael Ortiz · · 1 min read

A fountain pen resting on handwritten pages

Software ships with release notes. People rarely do. I started keeping a changelog on myself three years ago and it has been the cheapest useful thing in my working life.

How it works

Once a month, twenty minutes, one file. Not a diary and not a retrospective — a list of things that are now true that were not true before. Changed, added, removed. The same three headings a release note uses, for the same reason: they force you to name a difference rather than describe a mood.

The entries are mostly dull. Learned the keyboard shortcuts for the thing I use daily. Stopped taking calls before eleven. Started saying the number first in proposals. Nobody would read this. That is fine, because nobody does.

I can tell you what I believed last March. I cannot tell you what I believed last March without the file, and I used to think I could.

Why it beats remembering

Memory edits for coherence. Ask me how I came to work the way I do and I will give you a clean story with three turning points, and the story will be mostly false — assembled backwards from where I ended up.

The file does not do that. It shows a change arriving in a dull, partial form, getting abandoned, coming back eight months later, and only then sticking. Reading it is a reliable way of discovering that something I now consider obvious took me two years and four attempts to accept.

The one rule that matters

Never edit an old entry. The temptation is constant, because past entries are frequently embarrassing and occasionally wrong. But an entry you have revised is just your current opinion wearing a date, and the whole value of the file is that it contains opinions you no longer hold.

Three years in, the most useful pages are the ones I would most like to delete. I take that as a sign it is working.

Share
Rafael Ortiz

Written by

Rafael Ortiz

Keeps the reading lists honest. Finishes fewer books than he starts, and says so.

Mexico City, Mexico

Responses

Members can reply, and replies thread. Disagreement is welcome; the only rule is that it is about the argument.

Three more pieces on the same thread.

Craft · 1 min read ·

What shipped instead

We planned eleven features and shipped six. Writing down which five died, and why, turned out to be the most useful document of the year.