What Is a Changelog? How to Write One That People Actually Read wedocs.co

A changelog is a dated record of every notable change to your product, newest first. It tells users what changed, shows prospects you're still shipping, and cuts repeat support questions.

The post's core argument is that two documents share one name. A developer changelog is a CHANGELOG.md file in your repo for people checking whether an upgrade breaks things. A product changelog is a public page written in plain language for customers. Most guides confuse them, and choosing a format before deciding which you're writing is where teams go wrong.

The standard format comes from Keep a Changelog, with six categories from Added through Security. Only user-facing changes belong.

On writing, three rules. Describe outcomes not implementation. Never write "bug fixes and improvements." Flag breaking changes separately with a migration path.

It closes on where to publish and the mistakes that kill changelogs, mainly abandonment and missing dates.