How to use Confluence to churn out product release documents that dazzle

Written by Rina Nir

How to use Confluence to churn out product release documents that dazzle

We completed the configuration project. The team now had an Atlassian site that helped them develop their medical device quicker, along with all the required release documents in Confluence. Risk management report, functional specifications, unresolved anomalies reports, and all the rest. No more slogging on excel sheets or scripted exports from Jira. Now each report is a native Confluence page with embedded Jira data. The Jira Snapshots app lands static Jira data on each of the reports.

The Quality Assurance team lead had examined the setup and loved it. It’s one click to export each page and upload them “as is” to their corporate document management system (DMS). Unfortunately, their DMS was not Confluence, but that was a given. They could not influence the fact that official documents need to be uploaded to the corporate DMS.

The new setup was not only easier for the Quality Assurance team. The developers and product managers became hooked even before the official rollout. Everyone saw how it will save them time and speed up the release cycle.

Before giving the system her stamp of approval, the Quality lead had one more question. She was worried about flexibility and standardization going forward. By flexibility, she meant that their needs are bound to change. She wanted to understand how they can change the system to meet those new needs.
In standardization, she was looking at how they can guarantee consistency. They had many teams and they all needed to churn consistent release documents. She knew that the consistency of their documentation body is a super-power. It helps find information quicker and makes it easier to onboard people. Also, it always makes a positive impression on auditors and customers.

Well, Confluence does provide a good answer on both these fronts. In this post, I will go over the Confluence configuration. Focusing on these two needs:

  1. Flexibility: how the team can adjust their release documentation. Adjust- because the world is moving. From changing the footer layout to adding a column in the report. These should all be doable by the team itself, without expending too much effort or very high expertise.
  2. Standardization: how the system helps all users create reports that look the same.

Create your flexible release documentation cookie cutter on Confluence (with a couple of marketplace Apps)

Three elements build the backbone of our Confluence configuration: page templates, the Jira Snapshots app, and the Scroll PDF exporter app.
Here is how it works:

  1. Each report type exists as a Confluence page template. Removing the guesswork about the required structure and the required sections.
  2. Most of the release reports include a list of Jira items. Like the list of functional specifications or the list of known anomalies. Sometimes they include traceability reports. For example, the traceability from functional specifications to test results. We use the Jira Snapshots marketplace app to grab a timestamped copy of Jira data and embed it on the page. Our Confluence page templates are pre-configured with Jira snapshots macro. Everyone loves that there is no manual work involved in embedding Jira data in the release documentation. It is a massive time saver.
  3. We do need to share the release documentation with the authorities. Scroll Exporter templates are guaranteeing that exported reports are all styled the same. Branded and with all the document control information. You can choose to work either with the Scroll PDF Exporter app or with the Scroll WORD Exporter app. The capabilities are the same and the results are always first-rate.

Using Confluence page templates to help your team produce standardized documents

There is nothing scarier than an empty page. It’s what happens when I write articles like this one, but also when someone needs to write meeting minutes. That’s why Confluence comes, out of the box, with more the 100 (!!) page templates. From “All hands meeting” to “5 Whys analysis” and more.

It’s always an “Aha!” moment when people realize that they can add their templates to Confluence. In this organization, the Quality Assurance and product team put the foundations in place. They defined the set of release documentation and their exact content and layout. Then, they transferred this knowledge to Confluence page templates.

From this moment, any team member knows exactly where to start. The Confluence template has all the background information they need and all the tips and nudges to get them started.
The use of Confluence page templates does not only speed up the process of readying the document for review. It also reduces the review time- because the format and structure of the document are already ironed out.

Getting timestamped Jira data with the Jira Snapshots App

The native Jira Macros in Confluence render Jira data as it is now. For release documentation, you need to capture static Jira data at a point in time. It is like you need a baseline of Jira data in Confluence.

This is what Jira Snapshots does. And there is more: it also allows to grab multilevel reports from Jira. Think one-click traceability reports.
The beauty of Snapshots is that it saves loads of time, as it takes seconds to refresh the snapshot for the next release.

Scroll Word Exporter or Scroll PDF Exporter creates world-class official documents

Nowadays, everyone consumes documents as web pages. Still, when making regulatory submissions or sharing official documents with third parties, we use stand-alone documents. The document layout is formal and standardized to a particular stylesheet. A stylesheet that dictates font, page footers and headers, heading numbering, etc.

The Scroll Word Exporter and Scroll PDF Exporter apps are indispensable in this case. Any Confluence site that is used to author official documents should have one of them. The secret to consistent exports is the configuration of a Scroll Export template. This export template follows your organisation’s stylesheet. The administrator defines it once, and it’s available to users across Confluence. This removes the guesswork from the export process. Welcome to standardized official documents that dazzle!

Getting ready for a changing future

Once the page templates for the various release documents are in place and your Scroll exporter template is done, the system is ready to roll out. A short training suffices to get the Confluence administration on board.

The team can now react to changes: A new company logo? A minor tweak of the Scroll exporter template does it. Do we need a new field in the functional specifications? Add a custom field in Jira and change the Jira Snapshots configuration to include it. Or, if there is a need for a new section in the risk management report- adding a section in the page template takes minutes.

This answered the Quality leads concerns about the future. She considered all the areas where she needed flexibility and standardization and felt that she had a good platform for the future. She also knew that it would not take long until she became a power user herself and could work with her admins to put in place any required change.

Have an idea for your Quality Management System?

We’d love to learn more about your project.

Let’s have a chat