You're on your way to the next level! Join the Kudos program to earn points and save your progress.
Level 1: Seed
25 / 150 points
1 badge earned
Challenges come and go, but your rewards stay with you. Do more to earn more!
What goes around comes around! Share the love by gifting kudos to your peers.
Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!
Join now to unlock these features and more
The Atlassian Community can help you and your team get more value out of Atlassian products and practices.
Writing release notes is like building a house; before you start working on anything else, you need a solid foundation. Release notes are an underrated way to connect with your users and can be something they look forward to reading, rather than a chore. But none of it matters if the foundation isn't set.
In this article, you’ll learn how to:
build the foundation for your release notes in Confluence,
write and style release notes,
publish your release notes in different ways using Confluence.
By the end, your release notes will be informational and fun to read at the same time.
Want to get into details? Check out the full article on Building a Foundation for Your Release Notes on Rock the Docs.
Before we begin, let's decide where those release notes should go in your Confluence site. Ideally you setup separate spaces for each of your products in Confluence, then create a page in that space called ‘Release Notes’ to file all release notes under.
Your release notes pages need a naming convention, which will greatly improve organization and searchability.
Our fictional product CleverApp follows a good naming convention of 'Product name - YYYY-MM-DD'.
Now that we’ve got the pages all set up, we can start the release notes themselves. You will know what tone suits your users and whether they will appreciate humor or metaphorically buttoned up notes. Here are some tips on how to make your release notes easy to read for both groups.
Start each new page with a summary. So Users know right away if it’s interesting to them.
Use a heading for each new point. This will help readers to quickly find the content that’s interesting to them, as well as improve the overall readability of your release notes.
Use the Table of Contents macro. This helps to create a good overview of your release notes.
Include media to support your written content. Include screenshots of your UI, diagrams to illustrate processes, or any other media to support your release notes.
Here's an example with Scroll Viewport for Confluence, one of our own apps that lets you publish Confluence content as an online help center.
Here’s what our release notes look like. All of this was built in Confluence and published as-is. The most important thing is to collaborate. After all, that's what Confluence is best at. Make sure all relevant team members can review, comment, and contribute to the release notes.
Your release notes will increase in number over time, making it difficult to keep up. An overview page in Confluence can help. In our article on overview pages, we explain that an overview page is a page that surfaces information about all the child pages beneath it.
You can do so much more with an overview page than we've shown you here, but these tips should give you an idea of what you can do.
Excerpt macro: Add an Excerpt macro to each release note page and summarize the release notes there. Overview pages using the Children Display macro will display this text as a preview.
Create from Template: Once you’ve found a format that works for your team, turn it into a template and link to the template from a Create from Template macro so you can place on your release notes parent page.
As we're writing in Confluence, we have more tools at our disposal than basic editing and macros. When we build with Confluence, we can do some pretty powerful things.
Add Jira tickets: By creating a change log report, you can bring in all Jira issues from your upcoming release into your Confluence page. Users can view more information on each Jira issue once published.
Publish release notes to a help center: Publishing your Confluence space directly online and making it public has some drawbacks, like limited design options. Atlassian Marketplace apps allow you to publish Confluence content to a website. Scroll Viewport , shown below, or Refined are both excellent examples.
There is a subscription cost for apps like Scroll Viewport, but they allow you to publish your release notes with a style and look that matches your brand.
Congratulations, you have the foundation for your release notes set! It's now time to focus on the release notes themselves, writing them in a way that your users will enjoy.
Steffen Burzlaff _K15t_
5 accepted answers