Managing Technical Documentation Review Cycles in Confluence

Con­flu­ence makes it easy for tech­ni­cal writ­ers to facil­i­tate reviews of their con­tent. In this blog post, I’ll address some of the dif­fer­ent ways you can solic­it feed­back from Sub­ject Mat­ter Experts using Confluence—by track­ing changes right on the Con­flu­ence page, by upload­ing a Microsoft Office file to Con­flu­ence, or by embed­ding a PDF file inside of a Con­flu­ence page.

What is Confluence?

Con­flu­ence is an online col­lab­o­ra­tion tool that allows peo­ple to cre­ate, share, and dis­cuss files, ideas, min­utes, and tech­ni­cal doc­u­men­ta­tion.  It also pro­vides spaces where con­tent cre­ators can cre­ate and orga­nize con­tent and discussions.

I like Con­flu­ence because it includes a sim­ple user inter­face but also con­tains fea­tures that make it eas­i­er for tech­ni­cal writ­ers to per­form their jobs.

Option 1: Tracking Changes in Confluence

When you write con­tent in Con­flu­ence, then invite one or more Sub­ject Mat­ter Experts to review and make edits to a page, Con­flu­ence auto­mat­i­cal­ly tracks the edits. At any time, you can review the lat­est ver­sion of the con­tent and com­pare it against an ear­li­er draft.

To review a page’s history:

1  Nav­i­gate to a page in Confluence.

2  Click … and click Page His­to­ry.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

Con­flu­ence dis­plays the his­to­ry of the page.
[expand  title=“See the fol­low­ing screen cap­ture”][/expand]

3  On the Page His­to­ry page, you can per­form one or more of the following:

a. Review an ear­li­er ver­sion of the page by click­ing an ear­li­er draft in the Ver­sion column.

b. Restore an old­er ver­sion of the page.

c. Com­pare two ver­sions of the page. Con­flu­ence will show what’s been added, delet­ed, or modified.

The one pro­vi­so about Confluence’s track changes fea­ture is it’s not as detailed as oth­er author­ing tools. For exam­ple, if you have mul­ti­ple Sub­ject Mat­ter Experts review­ing a giv­en page, it’s not obvi­ous who made which edit. In addi­tion, if you antic­i­pate that a page may need to be rewrit­ten, then you’ll be faced with a sea of edits. I find this option works well if you expect light edits to con­tent you have drafted.

Option 2: Adding a Microsoft Office File to Confluence

If you antic­i­pate a lot of changes, use Confluence’s file list fea­ture to add a Microsoft Office file to a page. The ben­e­fit of this approach is that you can use Microsoft Office’s Track Changes fea­ture.  All changes that you make to the Office file are auto­mat­i­cal­ly saved in Confluence.

To track changes by adding a Microsoft Office file to Confluence:

1  Open a Microsoft Office file that you want to upload to Confluence.

2  Make sure that Track Changes are select­ed with­in the Microsoft Office application.

3  In Con­flu­ence, click … beside the Cre­ate button.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

4  In the Cre­ate dia­log box, click Show more.

5 Click File list and click Cre­ate.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

6  In the Cre­ate file list dia­log box, add a name for your file list and click Cre­ate.

7  On the new file list page, upload the Microsoft Office file.

8  Once the file is uploaded, select the expand­able arrow beside the file.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

9  To edit the file, click Edit in Office.
    [expand  title=“See the fol­low­ing screen cap­ture”][/expand]

As the file shown in this exam­ple is a Microsoft Word file, Sub­ject Mat­ter Experts can open the file in Word and make their edits with Track Changes select­ed. After they are fin­ished edit­ing the file, the doc­u­ment is auto­mat­i­cal­ly uploaded to Con­flu­ence. This approach pro­vides Sub­ject Mat­ter Experts with a famil­iar way of working.

Option 3: Adding a PDF to a Confluence Page

Anoth­er way to man­age your reviews is by upload­ing a PDF file to a Con­flu­ence page. When a review­er clicks the PDF, Con­flu­ence opens a sec­ondary win­dow where Sub­ject Mat­ter Experts can review the doc­u­ment page by page. With­in the sec­ondary win­dow, Sub­ject Mat­ter Experts can also add com­ments through the document.

In the fol­low­ing exam­ple, I’ve com­ment­ed on my own doc­u­ment to illus­trate how the fea­ture works.
[expand  title=“See the fol­low­ing screen cap­ture”][/expand]

This may be a good option when you want Sub­ject Mat­ter Experts to review your draft with­out actu­al­ly mak­ing edits to the source con­tent. On the oth­er hand, if get­ting feed­back quick­ly is an issue, this may not be the best option because you then need to incor­po­rate your edits into the source files.

From past expe­ri­ence, I’ve also heard review­ers com­plain about this sec­ondary win­dow as it can be a lit­tle unpre­dictable (for exam­ple, clos­ing unex­pect­ed­ly). It also does not allow users to search for words or phras­es, unlike Adobe Acro­bat Read­er or Adobe Acro­bat Professional.

Con­flu­ence offers mul­ti­ple ways for you to gath­er feed­back from Sub­ject Mat­ter Experts.