Every release I ship produces two different questions later. A user asks "what changed for me?" A month from now, I ask "why did I change it that way?" One document cannot answer both without getting long enough that nobody reads it.
So I write two short notes per release instead.
The user-facing note stays behaviour-only
Three lines at most, phrased as what someone can now do, or no longer has to do. No internal names, no library versions, no refactor mentions. If a change has no observable effect, it does not belong here at all — an empty user note is a valid outcome for an infrastructure release.
The private note records the decision, not the diff
Git already holds the diff. What it does not hold is the option I rejected. So the private note is three bullets:
- what I was trying to fix
- what I tried first and why I dropped it
- what would make me revisit this
That last bullet is the one that pays off. Six months later it tells me whether the constraint that forced the design still exists, which is usually the only thing I need to know before touching the code again.
Both notes get written before the deploy, not after
Writing the user note first surfaces releases where I cannot state the benefit in one line. That is usually a sign the change is half-finished, or that I bundled two unrelated things. Catching that before the deploy is cheaper than catching it in a support reply.
Keep them in different places
The user note goes wherever users already look. The private note goes next to the code, in a plain file per release. Putting them in the same place means one of them gets edited for the wrong audience.
What this replaced
I used to keep a single changelog and quietly stopped updating it, because writing for two audiences at once made every entry feel wrong. Two shorter notes with one reader each turned out to be much easier to keep up.
I write about this kind of small-scale shipping practice while running a portfolio of indie apps at Burning Tribe.
Top comments (0)