Send an Email or Publish to Confluence - What should you do with your release notes?

[#1]

Background

When you hear the words ‘Release notes’, almost always you think of an unsolicited email from a software vendor. But I am here to tell you that from our data, sending release notes via Email is the 2nd most common way preceded by publishing release notes to Confluence. 

Yup, you read that right. 

We are the developers of Automated release notes, an app for Jira. And we decided to find some insights about how our customers used the app. 

Here’s an interesting one we came across - in the year 2021, the number of release notes published on Confluence was at least ~2.5 times more than email ones. And we are only talking about our customers in the cloud, Server/DC data isn’t included.

To Email or Not To Email, that is the question!

This is an important question in a world where privacy has become a thing of a rarity on the internet. Not each one of your customers is going to be interested in receiving an email about new features or bug fixes in your app. Especially so, if you iterate quickly and release changes to your software every now & then. 

We recommend making it possible for your audience to subscribe/unsubscribe to the release notes communication on their own. This guarantees freedom of choice & makes your audience engage more with the release update communications. Because you are targeting the communication better.

Release notes on Confluence, but why!

Confluence is a Wiki software. But the availability of macros, external embeds & third party integrations make it extremely versatile for documentation purposes. Confluence acts like a permanent memory which does not run out of space. It offers an opportunity to collaborate & communicate with various stakeholders, not just the external audience. 

With page properties macro, you can easily create an index page for all your past release notes. This is a neat way to organise the release update documentation based on your target audience’s preferences.

Or you can create a single ‘running release notes’ page that continues to be updated every time a new version of your product goes live. You can use the ‘expand’ macro in this case to keep the page length in check.

Not only that, you can easily embed videos/gifs on the Confluence page to drive home your positioning with the release.

Email vs Confluence

	Email	Confluence
Access	In majority of the cases, emailed release notes are quickly accessible since they are available directly in the audience’s inbox.	Unless your audience bookmarks the Confluence page, access in this case remains a distant feature.
Engagement	Open & click rates, traditionally remain low on the Email channel.	Confluence release notes tend to offer better engagement because the user has navigated to the page on their own.
Content	Limitation on the type & volume of content.	You can use amost any type of content & formatting macros make it easier to manage high volumes.
Design & Layout	The screen space available in an email message is always limited, thus you are forced to use one of the common options.	Variety of macros, formatters make it extremely easy to customise design/layout of the Confluence release notes document.

The verdict

At Amoeboids, we are of the opinion that Release notes are under utlised & under estimated in their importance. Any customer focused team will look at Release notes communication as an opportunity to connect with their audience. 

Question shouldn’t be Email or Confluence? It should be who needs release notes via email and who needs them in Confluence. Additionally, are there any other formats our target audience is comfortable with? May be you can even publish the release notes directly in your app in the form of a widget or standalone release page. The possibilities are endless. 

Begin with a thorough analysis of your target audience, figure out which channels & formats are most appealing to them & generate release notes in all those formats to make the most of your releases.

How many formats do you generate your release notes in?

[Andy Gladstone]

Internal Release Notes: Confluence
External Release Notes: Web-based published via GitBook and distributed via link to our blog in our monthly customer emails.

[Anand Inamdar_Amoeboids]

Thanks @Andy Gladstone

good to know that you are already publishing release notes via multiple channels. Do you end up with different content for these 2 variants- internal vs external? And have you automated the process to compile these release notes documents or is it manual? 

Best,

Anand

[Deleted user]

Hi @Anand Inamdar_Amoeboids , this is a cool article. And I totally agree with you that release notes are unfortunately under-utilized!

My team have been thinking about release notes a lot lately and have done some digging into how other teams write, style and publish theirs. 

At K15t, we publish our release notes from Confluence to our help center. Our help center is created with one of our Atlassian Marketplace apps, Scroll Viewport.

Once live, our users can access the release content at any time and then go straight from the release notes to the relevant help article if they'd like to learn more.

We keep the release note content fairly 'light' and then get more technical on our help article pages.

Here's how the release notes look when published to our help center.

In regards to emailing our release notes, when we have something more substantial to share with our users, we send them an email with a link to the release notes on our help center. 

Cheers,

Gabriella

[Anand Inamdar_Amoeboids]

Good to know @[deleted] . Do you have a different variant of release notes for 'internal usage' or is it just one that goes onto your public documentation?
Curious to know.

Best,
Anand

[Deleted user]

Hi @Anand Inamdar_Amoeboids , we work on the documentation privately until it's ready to go live, then it's that same Confluence page that gets published to our help center – so just one source of documentation.