The changelog as a design document
Most changelogs are post-hoc lists: 'fixed a bug in the export modal' — useful to nobody, read by nobody. A changelog people actually read is written forward, in the language of decisions: what changed, why it changed, what was considered instead, and what the trade-off was. It is the public record of a design conversation, and users read it because it treats them as participants in that conversation rather than as recipients of updates.
- Lead with the why: 'the export modal now keeps your filters' beats 'fixed export filters'; the first sentence should make a reader who does not use export understand why the change matters to someone who does.
- Name the trade-offs: 'we made the dashboard denser to fit the new chart; the cost is a busier first screen, and we are watching the feedback' — honesty about costs is what builds the trust a changelog is really for.
- Credit the source: 'this change came from a support thread about…' turns users into contributors and proves the log is a conversation, not a broadcast.
- Show the work: a sketch, a before/after, a run log — a changelog entry with a visual is a case study; text-only entries are filings.
The cadence that works
The cadence question kills more changelogs than the writing: too frequent and entries thin out into noise; too rare and the log becomes archaeology. The pattern that works for a solo or small team is small and frequent — ship a change, write the entry the same day, publish weekly or biweekly. The discipline is that the entry is part of shipping, not a chore after it: if a change is not worth a changelog line, it is worth asking whether it should ship at all.
## [date] — [the change in one plain sentence]
Why [the problem, in user language]
What [the change, with the trade-off]
Who [the users this helps most]
Source [thread / audit / idea that prompted it]
Scars [what we tried first and why it failed]