5 Best Practices For Writing Great Release Notes

Sharing is Caring

Release notes are usually written in the present tense and provide details about any changes in a new software version. In most companies, the product manager is responsible for writing the release notes and it usually makes the most sense because they are often good communicators and good writers. Most product managers are technical enough to get by and often don’t know all the jargon.

Release notes are really important to put together because they celebrate the team’s wins and and can provide really useful information for users to keep in the loop about new product changes.

5 Best Practices For Writing Great Release Notes

Know your Audience

The most important thing about release notes is that they should be relatively free of jargon and should really be written for the perspective of a user of the product.

Releases notes should be really accessible to customers / users and support staff. I recommend not hiding them as they can be valuable to marketing and sales too!

Keep Them Brief

Release notes should be really brief and really easy to scan. This means headings, sub headings, bullet points, and small paragraphs are really valuable.

Group Them Logically

Release notes should be organized in sections about the features they are adding, improving, or removing things from. It’s really important that they be written in a way that makes them easily scannable so that people find what they’re looking for and what they need.

Write Release Notes Like They matter

It’s no secret that people don’t read release notes until a change potentially impacts them. Being a Salesforce developer, I’ve seen this first hand time and time again.

I’ve sent emails out or shared videos and nobody reads them until it’s too late! Behaving like nobody will read them doesn’t help us though, we need to be proud of all the changes we’ve shipped and make the notes exciting so we don’t end up with a self fulfilling prophecy.

I like to distribute release notes via Email, App Store (if applicable), in a Chatter group (if internal and applicable), and sometimes via social media. Social media is a really great way to spotlight ground breaking features and deliver some hype!

HubSpot has some really amazing blog posts they’ve done as release notes.

Show Value

Release notes are great way to show what’s being worked on and how it can be used. If something is really new and exciting, it’s awesome to produce a video for it.

The video can be a really short screencast, I like to use Vidyard’s free Cam and Screen Recorder.

Wrapping It up

Release notes are an incredibly easy way to keep your company’s support staff and users informed of any changes that are happening. Producing release notes doesn’t have to be hard if you are willing to invest a little bit of time and energy into knowing who the audience is and what they will use them for.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.