Oftentimes, Confluence is the place where Software Requirements are stored and maintained. Specifications for new versions of applications, microservices, integration requirements, and A/B test logs — to name a few types of requirement documents that can be found in Confluence spaces.
Aside from requirements themselves, these documents also contain a section dedicated to gathering approvals or verifications from the responsible people (Product Managers, Chief Product Officers, Product Analysts, etc.):
When a new specification is developed, its creator mentions responsible people who have to review the document and give their verdict. In an ideal world, the mentioned employees get an email, immediately open it, go to the specification, closely examine it, and approve or reject it. But in the harsh reality, approvers rarely open emails from Confluence, let alone give up their current important activities and rush to set a status on yet another specification.
Product Managers, Heads of Product, and other decision-making roles would prefer to have a single page where all the specifications requiring their attention would be presented:
In this article, we will create such a page (Status Report) step by step and sort out some tips to improve User Experience while working with the report.
Creating a Status Report
1. Formatting verification tables
To create a Status report, format verification tables (VT) on Specification pages in a particular way:
- VTs contain 2 columns.
- VTs have only Header column property, no Header row.
- In the first column (the header one), only the approvers’ roles are specified.
❗ Make sure you use the same role names in all Specifications. - In the second column, the status and the approver are specified.
- All VTs are inserted into the Page Property macro:
All Specifications that you want to build the Status Report for have to have this format for verification tables.
2. Labeling Specifications
Put the same label on all Specifications for the Status Report.
Examples of labels: requirements, specification, new_version, etc.
3. Creating the Status Report
- Create a new page titled Status Report.
- Insert Page Properties Report macro on the page.
3. Click on the created report and select the Edit option to configure the Page Properties Report:
3.1. In the field Label, specify the label that you put on all Specifications in step 2.
3.2. In the field Space, specify the space where all Specifications are stored:
❗ If your Specifications are distributed across several spaces, specify all of them.
3.3. Open section Options and set the following parameters:
- Title column heading — a name for the column with links to Specifications (for example, Specification);
- Columns to show — roles from verification tables that you want to include in the report (for example, Role 1, Role 2, Role 3);
❗ Roles must be exactly the same as in the verification tables. - Number of items to display — how many Specifications to include in the report on one page (for example, 30);
- Sort by — the column used for sorting the report;
- Reverse sort — whether or not to use the reverse sorting for the column specified in Sort By;
- Show total comments count — whether or not to include the total number of comments of the specifications in the report;
- Show likes/reactions count — whether or not to include the total number of likes/reactions of the specifications in the report;
- Show open inline comments count — whether or not to include the number of unresolved comments on the specifications in the report;
- Show labels — whether or not to include labels of the specifications in the report;
- Show creator — whether or not to include the creator of the specifications in the report;
- Show last modified time — whether or not to include the time when specifications were last modified in the report;
3.4. Click on the Preview icon to see the resulting report:
3.5. Click on the Save button to save the Status Report.
The Status Report is ready. Now, each time a new Specification with the properly formatted verification table and labeled “Specification” is created, it will be reflected in this report:
Promised Tips
Creating Templates for Specifications
To avoid formatting the verification table and adding labels manually each time a new Specification is created, create a Specification Template with embedded VT and necessary labels.
Here is an article about creating user-friendly Confluence Templates.
Excluding approved-by-all Specifications from Status Report
When a Specification is approved by all responsible people, most likely, it doesn’t belong to the Status Report anymore. It’s finalized, and approvers don’t have to perform any actions with it. So, how to exclude an approved-by-all Specification from the report?
The first news, is it’s possible. The second news, it requires a manual activity.
The only way I found so far is to add another label to Specifications. This label would indicate that a Specification is not finalized yet (for example, the label non-finalized).
So, the shift is in the second and third steps:
2. Labeling Specifications
Add another label non-finalized or to-approve to all Specifications:
3. Creating the Status Report
When editing your Page Properties Report macro, add another filter of type Label with value non-finalized:
It will do the trick when it comes to selecting Specifications to approve for the Status Report.
But after all approvers verify the Specification, a Project Manager or other responsible person has to remove this non-finalized label from the Specification so that it is excluded from the report.
🙄 This is the only way to build a Status Report on Specifications that need approvals I found so far. If you know a more practical and less demanding one, share it in the comments)
