The hitchhiker’s guide to release notes
A set of guidelines to write awesome release notes.
Throughout the years I’ve often been working on release notes. I found that many companies did them to tick a box, but they didn’t really believe in them being a user engagement and retention tool. Guess what? They can be if you approach them with a user-centric mind.
This article contains the guidelines I put in place when writing release notes. I shared it with someone in the Content + UX Slack, and they asked me whether they could share it inside their organization, so I thought I’d write an article to announce their public availability.
You can find The Hitchhiker’s guide to release notes as a Notion page. I published it there so that I can iterate on it in the future.
The guide has 4 main categories of recommendations:
- Content
- Style
- Formatting
- Collaboration
Recommendations span from what to include in the release notes to how to write bugs, and anything in between. Pair the guidelines with your company’s style guide or use them to spark conversations with your stakeholders, I’m sure you’ll start seeing the results right away.
Commenting is active on the document so, if you have any suggestion for improvements, or additional examples for Dos and Don’ts, I’d love to hear them—Let’s make this a collaborative document that is useful to the community.
Also, if you use the recommendations at your organization, I’d love to hear about your experience and whether it had any positive impact.