If you have worked in the software industry, you already know what is a release note. It is a communication tool to interact with your customer base. Formally speaking, a release note is a technical documentation written by a technical writer addressing the application-related information.
Application-related information includes:
- Release details
- Purpose
- Enhancement
- Bug Fix
- Important notice
- Description
- Screenshot
- Documentation
- Quick-installation guide
- Configuration of sources
- Samples
- Devices
- Previous changes
- Contact
- Release details outlines the name of an application, version, platform supported, downloadable application pak file, and release date. It is optional but recommended to have a digital signature to ensure the application pak file's final build is verified and accurate.
- Purpose outlines the purpose, i.e., enhancement or bug fix. Under enhancement, you list new changes, features, and/or improvements. Under bug fix, you list the issues fixed. A sentence should include a maximum of 25 words.
- Important notice outlines essential information that a user needs to know beforehand.
- Description outlines a general description of an application and its functions within your system environment. Be flexible and explain why an application exists in the first place. Avoid giving extra information on its background and working mechanism.
- Screenshot illustrates the end-result. You must blur out the confidential information in a screenshot using image editing tool like Snagit.
- Documentation outlines the types of a document like manual or guides accompanying a product. It lists the available document and its location. Most of the product documentation is available in a centralized repository, often known as a documentation portal.
- Quick-installation guide outlines the installation steps. The number of steps should be limited to 5 to 10 and written in an active tone.
- Configurations of sources outlines a necessary configuration file to be installed beforehand.
- Samples list the sample log source or sample code and relative output. It gives a quick idea to a user on how to get started. It is optional.
- Devices list the supported devices, if any. It is optional.
- Previous changes list the changes made in the earlier versions. It clarifies why a newer version of an application exists and how the application is evolving.
- Contact outlines the contact or support details.
Platform
Confluence is a remote collaboration software developed by Atlassian and is the most widely used platform for release note. Nowadays, several enterprises use the Confluence to create, draft, develop, collaborate to verify the release note, and store it for future reference.
You can view the release note maintained by the Confluence Confluence release notes.
Best practices for drafting a release note
- Use plain and natural language. Avoid any technical jargon (highly technical language). Keep it simple!
- Group the sections mentioned above in a logical order.
- Don't forget to add version number and release date. It is a standard practice to set same version number for an application and release note.
- Remember a release note is a structured note. So, keep a sentence short and straight forward. Also, the maximum word count for a sentence in 25.
- Abide by the style guide and a standard release note practice maintained by your organization.
- Try writing in an active tone. Your user will get a clear idea about an event and actor.
- Review your release note and get it review. Also, incorporate all the feedbacks from your reviewer.
- Maintain a knowledge base of earlier enhancements/bug fixes. You can use it as a reference while documenting current enhancements/bug fixes. It will be your handy guide whenever you are stuck or need to reuse a sentence.
- Be transparent and let your users know about the enhancements and bug fixes. Don't hide anything from your user because they are the ones who notify about an issue. Transparent enhancement and bug fixes help to retain users.
- Finally, add support and contact details.