A changelog is the only page where a software company cannot pretend. It says what changed, when, and what it means for the person using the thing. That is why it is also the most underused marketing surface.
Why changelogs fail
Most are a list of commits with a version number. They are written for the person who wrote the code, published because a process demands it, and read by nobody except the three customers who already know.
The failure is not tone. It is the absence of a reader: no decision, no consequence, no reason to open the page next month.
Write for the person deciding to upgrade
Every release note answers one question: what changes for me if I upgrade, and what breaks if I don't? Two sentences of consequence beat ten lines of implementation detail.
Keep the detail in the docs. Keep the decision in the letter.
Three changes, one example, one link
Our format for the monthly letter: three changes worth understanding, one example of how a customer used them, and a link to the docs. Not every commit. Not every week. The three that would matter to someone who is not in the repository.
The example is the part teams skip, and the part readers remember. It turns “we added a flag” into “you can now run this in half the memory”.
A changelog is a promise that someone inside the company is still paying attention.
Cadence beats volume
A monthly letter that arrives is better than a weekly changelog nobody reads. Regularity makes the archive useful and gives the team a deadline that is not a release.
The open source project we wrote for went from a few hundred subscribers to several thousand in a year. Same product, same releases; a different reader in mind.
Who writes it
The person who writes the release note should be able to read the pull request. Not review it — read it, and ask the author one question about who benefits. If nobody can answer that question, the release probably does not belong in the letter.
This is why we prefer an editorial retainer to a one-off launch post: the reader is built over months, not announced once.
If you want that promise kept, it starts with a decision about who the letter is for. The editorial retainer is described in Services.