How to write good release notes?
A release note is a report that accompanies new or updated software and details the technical features of the product. These notes provide end-users with a brief summary of the product for new releases. For updates to existing products, the notes educate end-users on what’s new and how the product has been improved since the last release. Here’s a short guide to writing good release notes.
Use a template
All release notes should include the following:
- Header: product name, release number, release date, etc.
- Overview: a brief overview of a product/feature/bug fix.
- Purpose of the release
- Summary: short description of the bug
- Resolution: brief description of fixed issues; feature enhancement.
- User impact: what impact will the new changes have on functionality and what actions are needed by users.
- Ongoing issues/limitations
Make release notes short and clear
Long texts are time and energy consuming, especially when it comes to technical information. Use plain language. Keep sentences short and break up long paragraphs. Stick to relevant information without being too vague or getting into the whole history of a product.
To ensure that your release notes contain all the necessary information try answering following questions:
- What was the problem?
- What did you change?
- Why was the change needed?
- How will it affect the user?
Post consistently
While some changes may be more significant than others, it is preferable to publish most of your updates as release notes. This allows readers to feel like they are part of your journey and gives them a sense that you are constantly improving. It also helps to keep yourself accountable. Knowing that users expect consistent updates can help you meet your deadlines more frequently.
Use reverse chronological order
Publish the latest changes at the top, so that users can see the most relevant information first. And they can scroll down if they want to see the history of progress.
Use visuals
The common writing advice “show, don’t tell” works in technical writing as well. Sometimes, it’s easier to show than describe something. Or rather it’s easier to understand visual information than a text description. Use visuals like screenshots, videos and GIFs. Accompanying text with visuals makes reading easier and more enjoyable.
Insert links
It is best to keep release notes short, but sometimes a major change requires detailed explanation. In such cases you can insert links to in-depth description articles and additional documentation. Links can help to keep users engaged. Link to related docs and resources and it will keep them on your site longer. Entertainment, usefulness and familiarity breeds attachment.