Writing · Work
Writing a changelog people read
Most changelogs are written for the people who made the change. A few rules that turned ours into something customers open on purpose.
Abi Okonjo, Contributor1 min read
Our changelog used to be generated from commit messages. It was complete, accurate and read by nobody, including us. Last year we started writing it by hand, once a fortnight. Now it is the most visited page on our site after the login.
Here is what we changed.
Write for the person at the front desk
Our customers are receptionists and practice managers, not developers. So every entry answers one question: what is different for you now? “Refactored the availability engine” became “Booking a double appointment no longer hides the next free slot.”
If a change has no visible effect, it does not go in. We keep a separate, technical log for that.
Lead with the best thing
Each release gets one headline: the change most people will notice. Everything else goes below it, grouped as New, Improved and Fixed. Nobody reads a list of twenty items with equal weight, but almost everyone reads a headline.
Show, then explain
One screenshot does more than a paragraph. When a screenshot will not do, a short example will. For the few customers who use our export, we show the actual output:
date,time,practitioner,patient_ref,duration_min
2026-09-01,09:00,Dr. Amsel,P-1042,20
2026-09-01,09:20,Dr. Amsel,P-0877,40Keep the dates honest
Every entry has the date it shipped, not the date it was planned. If something was rolled out gradually, we say so: “Rolling out this week to all practices.”
Say what went wrong
When a release breaks something, the fix goes in the changelog with a plain sentence about what happened. Customers trust a changelog that admits mistakes far more than one that only reports progress.
Writing it takes one of us about an hour every two weeks. It is the best hour of support work we do.
