Building a Foundation for Your Release Notes

[#1]

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.

Structuring Your Release Notes

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'.

Best Way to Format Your Release Notes

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.

Using the Overview Page

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.
  
  

Add Value Using Extra Confluence Tools

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.

[Srinatha T]

Insightful article. Thanks for sharing

[Courtney - TechTime]

Awesome, thanks for sharing! 

[Sean Manwarring _Izymes_]

Great read Steffen!