You can review docs from within Confluence by adding pins and comments to the PDF. This doesn’t actually modify the PDF, it just modifies Confluence’s metadata about the PDF.
This has the following advantages:
- Everyone can comment on the same version of the PDF, including having a conversation right there and then about changes.
- Everyone can easily find feedback and the history of changes.
- It’s easy to see when changes are implemented.
- It’s easy for developers and other reviewers.
- Confluence supports versioning, including comments on multiple versions of a doc.
Background:
For over 5 years, I’ve worked with a small top-notch team. We all work remotely on multiple products, so Confluence and JIRA help us stay organized and connected. Here’s how we do doc reviews.
I use MadCap Flare to create the docs and I publish them as both PDF and HTML.
Our team uses JIRA to track bugs and new features and group them into releases. In JIRA, I add the Documentation component to all bugs/features that require doc updates. Once I have updated the source documentation, I add the Documentation_Complete label. This helps me stay organized. I have email subscriptions to keep me up to date, as sometimes developers add the Documentation component for me.
In Confluence, we create a product release page with information such as the release date, pie charts of progress on the JIRA issues, contact info for the people working on the release.
I create a child page called “Documentation Notes” for each release. It’s a mini doc plan. I have links to each JIRA issue in the release, and then below that, there’s information about the changes I need to make in the guide for each issue. I document many products at the same time, so I need to be very organized. (If you’re interested, here are links to my docs: http://connectors.lionbridge.com/Home.htm and http://docs.clay-tablet.net/Home_CTT.htm)
I make all the changes in the docs, create PDFs, and post them for review on the release page.
When we switched to this process nearly 3 years ago, I documented it on a page in Confluence, so that the rest of the team would understand what to do. It works really well, and it’s easy for new team members to understand and get up to speed.
Here are my instructions for my team members/doc reviewers. My own process follows, below, at the bottom of this post.
How to review a doc in Confluence:
When a doc is ready for review, I upload it to the relevant product release page in Confluence, and add a comment to the page that it is ready for review. If you are a reviewer (either QA or dev), I tag you in the comment. I add pins to the places in the doc that I’ve changed, along with a reference (e.g. a JIRA ID) of what is documented.
1. In Confluence, open the relevant product release page.
2. Click the link of the PDF to review.
The PDF opens in Confluence in your browser. By default, the latest version of the file is displayed.
Tip: To view a different version, select it by clicking the dropdown arrow after the file name and version number.
The pin icon in the top-right corner indicates the number of pins in the metadata for the current version of the document:
3. Click this icon to navigate to the first comment in the document.
Alternatively, you can click this icon within the PDF to display the corresponding comment in the right pane.
Tip: To increase the zoom of the PDF so you can see it more clearly when the comment pane is displayed, click the Fit to page icon in the bottom center of the PDF.
4. If the change you are viewing is fine, click Resolve. The comment disappears.
Tip: To view resolved comments, in the top-right corner, click More (…) > Show resolved comments.
5. If the change you are viewing is not OK, click in the Reply box under your name and enter your comment.
If your comment is really long, you can comment on the relevant product release page in Confluence (where the PDF is attached) and tag me.
6. To navigate among pins, click the arrows.
I will update the docs, pin changes I want you to still review (non-trivial changes), and upload a new version to the product release page in Confluence.
Finally, here’s my process for doc reviews:
1. When I post the draft for review, I add pins for all sections that need review, and I include JIRA IDs where relevant.
Tip: I include the version # in the doc file name, so that Confluence differentiates it from other versions of the same doc.
2. In a version with feedback, I reply to all pins/comments:
- If I fix it, I will comment that it will be fixed in the next doc version.
- If I don’t fix it, I will add a comment about that.
3. In a version updated based on feedback:
- I will not add pins for trivial updates based on feedback.
- I will add pins/comments only for what reviewers need to recheck, and I will tag the reviewer.
4. I will keep posting docs on the release page until they are final.
Tip: Unfortunately, Acrobat bookmarks are not available when PDFs are open in Confluence. I keep a version of the file open in Acrobat so that I can easily find the correct page number.
For more about this feature, see: https://www.atlassian.com/blog/archives/introducing-new-feedback-loop-confluence-5-7.