How to Set up Document Review in Confluence

In this article, we show how to set up document review in Confluence and what tools you need for this based on the experience of logi.cals.

In brief, logi.cals uses the following review funnel in Confluence:

1. Frame the review process with Comala Document Management app
2. Define document states and transitions between them
3. Add approvers for the document review
4. Use Talk – Advanced Inline Comments to capture required edits 
5. Assign the edits with the Mention feature
6. Suggest changes to automatically apply the edits
7. Highlight the processed Talk comments with color and prioritize them
8. Build Talk Report to see either the open or processed comments
9. Resolve all the comments and suggestions before publishing a document

Who is logi.cals

logi.cals creates automation toolchains for industrial automation solutions. The automation toolchain applies to complex systems such as hydroelectric power plants, buildings, ships, buses, machines, etc. The core technologies include runtimes, an engineering toolkit with a wide range of programming languages, and engineering bus architecture.

logi.cals operates in a highly-regulated industry that involves endless paperwork. They use Confluence as a hub for storing documentation. The team of logi.cals shared with us how they established a review procedure to control the document’s lifecycle from the draft version to the published (final) state in Confluence.

Feel free to watch our interview with Harald Nistelberger, who is an Atlassian admin at logi.cals. He demonstrates how they’ve set up their review procedure we describe in this blog post.

The document review in Confluence by logi.cals

The review process at logi.cals is under the control of Comala Document Management. The app allows to define the state of a document at each step of a review workflow and assign approvers. logi.cals uses the following statuses to establish the review pipeline in Confluence:

• Draft
• Ready
• Reviewed
• Rejected
• Published

A document starts with a draft. This state indicates that only users with edit or admin permissions can access the document. When the document is ready for review, the author switches its status to Ready with Comala Document Management and assigns team members to review it. 

At the next step, Talk – Advanced Inline Comments comes into play. While checking a document, the reviewer captures all the findings in the Talk comments. Often, it’s not only the document’s author who needs to address issues. The Mention feature allows adding other stakeholders to contribute.

After the review, the reviewer changes the state of the document to Rejected for further improvements.

Once the author and all the contributors get notifications about the Talk comments, they can start editing the document. With the Talk app, the team can do it in edit mode right away.

After making changes, an employee who made the required edits states that the Talk comment was processed, marking it in green with the Talk Color feature. As a rule of thumb, they add the Medium priority to them that signals the same.

After that, the document switches back to the Ready stage.

Manage tasks in Confluence with Talk Report

When the document gets dotted with comments, finding the comments assigned to you takes time. Moreover, project documentation can have hundreds of pages, which makes it hard to find the tasks that need to be fixed by you. In this situation, the author and contributors can use the Talk Report feature to see the tasks in the document, their resolution, and who they are assigned to. Besides, they can upload the report both for a space and a specific document.

How to insert Talk Report

To make it easier to find the Talk comments, logi.cals uses Talk Report along with the Table Filter and Charts app. For example, a document editor needs to find unanswered comments assigned to them. In this case, they add Talk Report in their personal space and apply the Status and Mentions filters.

A reviewer uses Talk Report with Table Filter and Charts to check the comments that are already processed and need review.

As you see, you can’t filter the Talk comments by color. But you can distinguish them by priority. The medium priority makes it easier for logi.cals to find already processed talks. When a talk has a Low priority set by default, it says the comment still needs a reply. 

After completing all the review cycles, logi.cals compiles a review protocol and sends it to the certification body. In the report, all the comments must be marked as resolved.

When the certification body gives the review protocol back, logi.cals documents its findings in the Talk comments. After stakeholders’ approval, the page moves to the Reviewed step of the workflow and then can be Published. It means the page can be visible to all Confluence users who can see the space with this document.

Suggest edits in Confluence

It’s not only the Talk comments that logi.cals uses for adding changes to a document. Another handy feature in the Talk app is Suggestions. It helps them to automate the process of making changes to the content on a page. Generally, they use it in the following situations:

• The reviewer corrects spelling mistakes  
• The reviewer suggests paraphrasing a sentence
• The reviewer adds more details to the content

If the author of a document agrees on the changes that need to be implemented, they accept the replacement. Once accepted, changes automatically apply to the text.

If the author of a document doesn’t want to apply changes at once, they can:

• discuss with a reviewer why this fix doesn’t work
• agree on win-win corrections
• reject changes
• use the Suggestion feature to apply the negotiated edits

At logi.cals, it also might be the case when the page is in the Release state, and the author wants to change something. Talk Suggestion can help automatically document the changes in Talk Report. The author adds the suggestion to the place that needs to be updated and accepts it. It helps all the stakeholders track changes.

Using a bundle of Talk and Comala for document review

Many business processes require formalized procedures for creating, approving, and publishing documents. While Сomala adds a level of control over the document, Talk ensures the accuracy of changes. Every employee involved in the review process should know what, where, and how fast to make required edits. In the Talk comments, you can capture requirements and then report on the addressed changes to the review body.

Using both tools in a review process helps you speed up the publishing of a document and encourage adherence to the procedures a company must comply with.