When writing release notes or changelog entries it's important to keep some things in mind. First and foremost it is important to be aware of who the release notes are for.
Release notes are not for you...now.
Release notes are for future you.
Release notes are for a user who wants to know what the latest updates are.
Release notes are for a stressed-out colleague who's trying to narrow down when they think a particular breaking change might have occurred.
Identifying the personas of the people who will be reading release notes is important so as to effectively communicate with them. If you don't understand your audience you may end up losing them.
If you write bad release notes for a product, you may frustrate your users into finding an alternative solution that feels more stable, or is more predictable.
If you write bad release notes for a client, you may end up confusing or angering them.
If you write bad release notes for your team, you may end up alienating your maintainers and slow the pace of progress.
Read More ⇨