Documenting your software releases is an integral part of a software development team's job, and it's almost as important as shipping itself. Why? 

• Increased visibility - Documenting your releases offers a window into the work your team is doing and how it's progressing toward project milestones. 
• Continous improvement - Agile teams seek to improve every release. Having a regular cadence of release reports allows teams to see what they've done, and how they can improve.
• Historical reference - Always go back and see what was done in specific releases. 
• Better communication - Clearly report to support and ops teams what was in the release and provide issue links for more detail.

But here's a guess: this is probably one of your team's least favorite things to do. Well, we've got some good news: it doesn't need to be an annoying chore or a giant time suck.

If you track and report most of your work in JIRA, the integration between Confluence and JIRA makes it easy to insert your release results straight from JIRA into a Confluence page, where you can add more color and detail, publish internally, and also make them publicly available.

Create an internal release report

Start with the JIRA Reports Blueprint in Confluence. Select Create from template from the top nav (3-dot button next to ) > JIRA report > Change log  Create          

Select the Change log report to create an internal release report. This report type gives you a detailed summary of the JIRA issues that were completed in a given release or project. Confluence guides you through creating the report and you can clarify which release you want to report on and what to include.

Select the appropriate project. (If you have more than one JIRA instance, also select which site you want to use.) Complete the appropriate fields for the Create a change log screen and select Create. Your change log report will include the data you specified from JIRA, as well as other important page elements that you can edit and fine tune. 

You can either create a dynamic or a static list of issues. Because release notes are a point-in-time communication, a static list is best. If you'd rather include a dynamic list, hit the Switch to advanced link and enter custom JQL. (See the documentation for the JIRA report blueprintfor more details.)

Here's what the page looks like in edit mode.

The top of your page:

And after you've saved:

As you can see, this  change log  is  focused on bug fixes.

Confluence will automatically break your release down into "Bug Fixes," "New Features," "Improvements" etc. based on the issue type in JIRA. This automation is really helpful and eliminates the need for lots of manual editing and formatting.

Create public facing release notes  

Craft the perfect release notes for your customers again and again by creating your own release notes template. Here's an example of the template we use when publishing JIRA release notes on our documentation site.

In the template, we've included instructional text to help guide the page creator. The most important thing to include at the top is a small blurb summarizing what's in your release, or the major theme. If it's just a bug fix release, however, there won't be much to add in this space. But if it's a major release, consider adding a blurb about the impact of new features, functionality, etc.

The page includes:

Macros :

• • Table of contents macro – Gives a brief summary of everything in your release notes.
  • JIRA issues macro – Details all the issues that were resolved in the release as well as how many votes popular issues have received.
      

Page enhancements :

• • Screenshots and video – For major releases, you'll want to add screenshots and demo videos to show off new features and improvements.

• • Permissions and restrictions – Permissions are important with release notes. Keep release notes private while you draft, and make sure to review them thoroughly. (Inline comments in Confluence are reeeeeally handy for reviewing docs.) Once they are ready for the public, you can adjust viewing restrictions. (For even more details, read our guide on using Confluence for public-facing technical documentation.)

Edit and organize your release notes template

You can add more detail to your page templates wherever you like. You can organize your internal and public-facing release notes into what was shipped or fixed, with sections for "bug fixes" and "new features and improvements." Add macros, include images, screenshots, and video... the sky's the limit! 

Just remember two things:

1. Your release notes are important to people both within your organization, and without.
2. Setting up release note templates in Confluence will help you keep both audiences informed with a minimum of hassle.

6 content considerations for your release notes

1. Audience: Who will read your release notes? Think about your audience before you create them. 

2. Timing: When will your readers need access to the release notes? Day of release? Before? Use this info to schedule release notes around deployment, to allow time for review, etc.

3. Done: What was completed? Separate your release notes into sections—new features, enhancements, and bug fixes. This makes it easy to see things at a glance.

4. Edit: If you have multiple contributors to your release notes, they might add info you don't want a reader (internal or external) to see. Edit your release notes carefully.  Note: sometimes more detail, screenshots, etc. about one feature or enhancement than another will be seen as a reflection of the relative importance or complexity of that item.

5. Facts first: Stick to the facts. Release notes should be on point and concise. 

6. Story and message: A storyline can help put your improvements into context. Help readers understand the changes you’ve made and why they're important to them.

Remember, by using a shared document that developers and product managers can update on an ongoing basis, you save yourself from having to do everything at the end. Also, your release notes can seed other communications. Use the content for in-app notifications, product tours, blog posts, newsletter items, or help and support material.

At a glance: let's review

A well designed release notes page template – along with thoughtful, helpful content – will help you create release notes that not only fulfill the duty of documenting your work but something else: good, repeatable, and consistent communications that deepen your relationship with your audience.

Things to add to your release note page templates:

• Table of Contents macro : Create a list of heading links for quick navigation.
• JIRA issues macro : Detail all the issues that were resolved in the release and show issue voting.
• Excerpt macro : Reuse certain content for your release notes.
• Include Page macro : Include content across multiple pages.
• Horizontal rule: Divide sections of your pages by selecting from + Insert menu.
• Permissions and restrictions : Take control of who can view your pages with permissions and adjust viewing restrictions.

Did you create a nifty release notes page? Tweet a screenshot to @Confluence and win some swag!

Loved this page? Share it on Twitter