Release Notes provide an opportunity to showcase and celebrate your product improvements, based on planned innovations combined with popular suggestions from your valued customers. Download our easy-to-follow release notes template and start creating your own.
Large and medium enterprise software vendors publish release notes to accompany every new software update or substantial new version of their software. They typically include information on the new features, improvements, and fixes.
In this blog post, I explain how to create your engaging and relentlessly useful release notes using our release notes template.
Who Reads Release Notes?
Let’s look at who reads release notes. If, as we recommend, release notes are published first on your website as a blog post and then shared across email newsletters and social channels, then your audience will be made up as follows:
- Permission-focused system administrators
- Technically capable developers, for whom new features and upgrades are long-awaited
- Those researching a new software solution
- Your internal Marketing team, only some of which will come from a technical background
- Your internal Support team
- Direct competitors
- End users (less often than you might imagine)
Given the audience is mixed, clarity is more important than anything else. You must write for the least technical potential reader, while providing some technical detail and links to further information to satisfy those hungry for configuration options and wider implciations.
How to Use Jargon
- Release Notes can often descend into technical speak that is understandable to a few insiders. Remember the list above. You’re writing for those who are unfamiliar with your product just as much as for those who use it regularly. Not everyone will have a technical background. Adhere to the following simple principles:
- Refer to features, windows, options and other functionality by their official name, and be consistent about those terms
- Explain what each item does and how it can be used to help users achieve their aims – in Plain English
- Clarity is queen. Your release notes must clearly show what the new features are or what has changed and the impact of those changes. Vagueness wastes just as much of time-poor readers’ energy.
For further information, see When to Use Jargon (written for a copywriting context but applicable anywhere) and Plain English.
What Should a Release Notes Blog Post Include?
This section sets out our template for what should be included in a release notes blog post.
Some of this information is usually contained in terse, bullet point form – and often in impenetrable tech speak – in the Change Logs.
General Principles
- Briefly explain how the feature works and what it enables users to do
- Avoid listing out step-by-step instructions (save those for the comprehensive knowledge base article on the feature)
- Add screenshots and diagrams to help illustrate the feature
- List no more than 4 features, adding further ones in a bullet point list only
- Always include links to further information
Heading
The blog post title (H1 title) should include the product name and update name or number then ‘Release’ or ‘Update’:
Example
- [Product Name], [Update Name/Release Number]
- RapidSoftware, Ohana Update
- RapidSoftware, 3.4 Release
Overview
Start the blog post with a short paragraph overview of the new features, improvements, fixes, and removals (features that have been removed or are no longer updated or supported). Avoid going into too much detail at this point. Include a bullet point list if there are more than 4 new items.
Example
First Big New Feature
- Write a substantial paragraph describing the new feature in Plain English, highlighting the use case (what it enables a specific user to do in a specific context)
- Add a screenshot and/or diagram
- Add a link to a product page on the website or a knowledge base article for additional information.
Example
First Smaller New Feature
- Write a short paragraph describing the new feature in Plain English, highlighting the use case (what it enables a specific user to do in a specific context)
- Add a screenshot and/or diagram
- Add a link to a product page on the website or a knowledge base article for additional information
Example
First Improvement
Write a short paragraph describing the new feature in Plain English, highlighting the general benefits for all users. Add a link to a product page on the website or a knowledge base article for additional information.
Example
Fixes
Write a short paragraph outlining any important fixes that a user would notice in the UI, or a developer might notice in the backend or admin UI login.
Example
Further Information
Conclude the blog post with a section that links to product pages on the website or knowledge base articles for additional information.
Example
Promote Your Release Notes
- Write a short email newsletter with a short summary of the big new features, their capabilities and benefits, and link the call to action button to the release notes blog post
- Schedule a series of social posts that highlight the big or small, new and improved features, with a teaser
- Follow up the release notes blog post with a series of blog posts on each of the big new features of the update.
Do You Need Help Implementing Our Release Notes Template?
Contact us if you need help to write and promote understandable and relentlessly useful software product release notes and other product documentation your readers will love and share.
Photo by ThisisEngineering RAEng on Unsplash
