How to Maintain a Documentation Baseline of Agile Development in Confluence?

28 Sep 2022
by Marion Lepmets
Table of Contents

    Data are Always Up-To-Date in Jira and Confluence

    One of the key requirements and benefits of Jira’s collaborative work and Confluence’s concurrent document management is that data are always dynamic. Jira issues, Confluence documents and their macros are always up-to-date based on the latest input provided by your team members.

    Why is this a Problem?

    • The report I have made keeps changing in time!
    • The content of the page I approved and signed has changed!
    • I cannot create a baseline for the documents that will remain the same over time!
    • I cannot see what was the status when we started!
    • These tasks were not completed during last meeting!
    • What exactly has changed between certain dates?
    • I need to create a report of my work from a certain point in time!

    These are some of the complaints we have heard from our clients in the regulated domains using Jira and Confluence over the years.

    To take full advantage of Jira and Confluence, you are most probably using their built-in JQL queries and macros. Just remember that the content of those will always be dynamic. This is a blessing when you want to make sure that everyone in the team has the most recent information but a curse when you need to have an audit trail that illustrates your progress over time. This is especially true in complex, safety-critical systems development and in the regulated domains.

    How to Capture & Freeze Data in Confluence?

    SoftComply Static Snapshot app was developed to support Confluence and Jira users to capture and freeze data for exactly the reasons listed above.

    You can freeze the content of your Confluence page with the SoftComply Static Snapshots app to:

    • create (and keep) reports of your project;
    • keep a baseline of your document/Confluence page;
    • keep the status of tasks for the meeting notes;
    • monitor your progress;
    • ensure that the content of a page remains unchanged after you have approved/signed it;
    • store the (history of) meeting minutes.

    3 Most Popular Use Cases

    The most common use cases for the SoftComply Static Snapshots app are following:

    1. Capture and freeze the Jira issues macro (e.g. in the Meeting Notes).
    2. Ensure that the content of the approved document in Confluence remains unchanged over time.
    3. Compare the older reports to their latest version to understand what has changed overtime.

    I. Capture and freeze the Jira issues macro

    One of the simplest and most common ways to keep track of your project’s progress in Confluence is to use Jira issues macro. With a Jira issues macro you can display the status of any Jira issues in a report or at a meeting.

    Now, let’s say that you created a report or added the Jira issues macro into your meeting notes. After the meeting, your team goes back to work and the status of the tasks that you looked at during the meeting will start to change.

    The baseline of your report is gone as you cannot access the original content of the Jira issues macro any longer.

    Following steps below illustrate how you can capture and freeze the content of the Jira issues macro for baselining purposes.

    Step 1. Add a Jira issues macro to your Meeting Notes in Confluence

    A common way to understand the status of work is to add a Jira issues macro to your meeting notes in Confluence.

    In the picture below you will see a meeting notes taken on September the 12th including a Jira issues macro listing 3 requirements in total as risk mitigation actions.

    Original Meeting Notes from Sept 12th

    10 days later, when you look back to the meeting notes from September 12th, you will notice that the list of Jira issues has changed – there are 3 new issues in the list that were not there originally. In other words, your report baseline has changed and there is no way to go back to the original content from September the 12th.

    The Meeting Notes of September 12th has changed when you look at it again a week later

    To overcome this situation and keep the baseline you had at the Sept 12th meeting, use the SoftComply Static Snapshots app and make the content on the Jira issues macro static.

    Step 2. Take a Snapshot of the Meeting Notes that includes the Jira issues macro

    To capture and freeze the content of your Jira issues macro, simply go to the SoftComply Static Snapshots app’s byline item to “Take the Snapshot” of the page right after your meeting. This way you will have a report baseline stored for future reference.

    Taking a snapshot of your Meeting Notes including the Jira issues macro

    Step 3. Access the Snapshot of the Jira issues Macro and the Meeting Minutes anytime

    Every time a Confluence page is “snapped” it will be stored and listed in the Snapshots app page. You can access it from the sidebar menu of the Static Snapshots as illustrated below.

    Static Snapshots app page listing all the snaps of the space

    You can also list snaps of your choice on a Confluence page by using the “Snapshots List” macro, as illustrated below.

    List your Static Meeting Notes with the Snapshots List macro on a Confluence page

    II. Ensure that the content of approved/signed document in Confluence remains unchanged

    When using Confluence for your electronic Document Management System, you often approve and sign the content of various Confluence pages. Without using the Static Snapshots app, you may be signing pages the content of which will be changing in the future. This is not an issue if you use only plain text or images, i.e. the static information on page. But it will start to affect your work when you put Confluence’s full capabilities to use. To ensure that the dynamic content of reports will remain unchanged after you have approved them, you should first capture and freeze the content of the page and only then approve/sign it.

    Let’s take an example of the SoftComply Risk Manager reports. You are managing your risks in Jira with the SoftComply Risk Manager and you are creating risk reports in Confluence using the SoftComply Risk Manager for Confluence. All reports need to be approved and signed periodically by the stakeholders.

    Step 1. Add your Risk Report to your Confluence page with the Risk Table macro

    To report your product risks in Confluence, simply add the Risk Table macro to your Confluence page as illustrated below.

    Visualise a Risk Report on your Confluence page with the Risk Table macro

    Step 2. “Freeze” the dynamic content of the report before approving/signing it

    To “freeze” the content of the report, simply take a snapshot of the Confluence page where the macro is on and “lock the page” using that snapshot before signing it.

    Once the page is locked with the Statics Snapshots app, the byline item will turn green and state that the page is “Locked”, as illustrated below.

    Locking your Confluence page before approving it makes the dynamic page content static

    Step 3. Approve the document now that the page content is static

    Now it is time to gather approvals or apply your own signature on the report, as needed. You can be reassured that the content you have approved, will remain “as is” for future reference.

    Having the green icon stating that the page is “Locked” on your Confluence page means that the content is made static.

    You can revert a locked page back to the dynamic view and see what has changed over time by simply unlocking the page when needed.

    More information on how to use Static Snapshots app together with the Comala Document Management and Publishing apps as part of the Cloud eQMS Solution.

    III. Compare the previous reports to their latest version to understand what has changed

    In order to understand how much work has been done or what exactly has progressed over time, you may want to compare your most recent reports with the ones you have taken snapshots of earlier.

    Step 1. Choose the Versions of your Reports for Comparison

    To do that, simply go to the Static Snapshots app list, choose the versions of the reports you would like to compare to each other. You can also compare any of your chosen snapshot with the dynamic version of the page as well.

    Compare the report baseline to its current status to monitor progress

    Step 2. Analyse what has Changed Overtime

    Once you have chosen to compare two versions, you will have a similar comparison view that is native to Confluence’s page comparison.

    Comparison of two snapshots highlights the changes that have occurred over time

    LEARN MORE about the Static Snapshots app

    For more information about the SoftComply Static Snapshots app you can BOOK a DEMO with us, read more in our BLOG POST or the USER MANUAL.

    You can also check out a SHORT VIDEO TUTORIAL on Taking a Snapshot of a Jira Issues Macro or TRY THE APP OUT FOR FREE!

    Try us out on

    SoftComply apps are available on Atlassian Marketplace – you can try them all out for free!