The release goes out on Thursday, and the person who usually writes the notes is on holiday. Your lead asks if you could do it this time. You open the list of merged pull requests. Forty seven of them, with titles like fix flaky test, bump dependencies, and refactor order service.
The first draft most people write is that list, tidied up. It is accurate, and almost nobody can use it. Release notes are not a record of what the team did. They are a message to people who have to decide whether anything changes for them.
Start by asking who reads them. Customers, support staff, other teams who call your API, the sales team about to demo the product? Each one wants something different. If you have more than one audience, it is fine to write a short section for each.
Put anything the reader must act on at the very top. A setting that changes its default, a field that is being removed, a step they need to take before upgrading. Say what they need to do, and by when. Nobody should discover a breaking change in the ninth bullet.
Then describe changes in terms of what the reader sees, not what you changed. Not refactored the export queue, but large exports now finish in minutes instead of failing after an hour. If a change has no visible effect for this audience, leave it out. A list of internal work makes the important items harder to find.
Ask the people who did the work. A two line message to each author asking how would a user notice this will get you better sentences than reading their code.
Give the support team the notes a day early. They will be asked about the changes first, and they will often spot the item you described in a way customers will misunderstand.
Keep the tone plain. No marketing words, no excitement. Readers trust release notes that sound like an honest account.
And keep a template once you are done. The next person who is asked at short notice will thank you.
– Asael Shinder
Top comments (0)