Writing Good Release Notes

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.

Release notes should be

  • Clear
  • Brief
  • Past Tense
  • Links

Clear

Release notes should avoid any unnecessary jargon.

Some amount of jargon may be necessary within a project to refer to terms used by anyone familiar with the project. For example, release notes about Twitter might refer to a "tweet", while release notes about Facebook might refer to a "status".

Otherwise, avoid big words.

Don't say "implemented" when you mean "created". Don't say "resolved" when you mean "fixed".

Brief

Use as few words as necessary to get the point across.

Past Tense

Release notes are read after the release has happened.

Release notes in present or future tenses are awkward to read:

2017-11-06

  • Updates widget alignment from left to right
  • Removes gizmo inhibitor

vs

2017-11-06

  • Updated widget alignment form left to right
  • Removed gizmo inhibitor

Links

Release notes are teaser text for detailed descriptions that should be documented elsewhere. While it's important that the release notes contain complete thoughts so that they can be useful to the reader, it's equally important that release notes only contain a high level summary of the work that was completed.

To facilitate this, release notes should include some sort of link to the detailed description of the work that was completed. Particularly when using a ticket tracking system, release notes should reference ticket numbers and link directly to the tickets they represent.

Good release notes facilitate effective communication

When written properly, release notes can help developers communicate efficiently with their team, management, client, and users.

Instead of constantly being pestered about what work has been done, or the status of a particular feature, proactively sharing release notes can lead to less interruption as everyone learns to expect that they will be told when work is ready without needing to ask about it.