Introduction
In the 2015 Summer issue of ISTC's Communicator journal, Marjorie Jones wrote about an ingenious way of using styles to mark up changes, insertions, and deletions within Flare topics. This enabled her reviewers to locate and focus on changes in published PDF or Word output.
Flare's built-in Track Changes feature was not an option because (in Flare versions 11 and earlier) tracked changes are stripped out of all published output (including PDF and Word). MadCap's reasoning was that you would not normally want end users of your published content to see changes unless they have been accepted. Note that Flare 12 now provides an option (in PDF Target settings) to include tracked changes with mark-up and annotations in the output.
There is, however, an alternative way of making content available for review from Flare: you can use Contributor, another product within the MadPak Suite. Contributor is a cut-down version of Flare that enables reviewers to work with topics sent to them from Flare. They do this using an XML Editor that is almost identical to the one provided by Flare.
Benefits of using MadCap Contributor
- Reviewers are easily able to focus on new content because they can see your tracked changes.
- Reviewers have access to the same authoring features as you, including styles, images, tables, and variables.
- All changes made by reviewers are automatically tracked, and as the original author of the content you are able to accept or reject these changes when you bring the topics back into your Flare project.
- You do not need to copy or re-type any of the insertions that you accept from reviewers, making the review and update process more efficient and less prone to error.
Potential downsides of MadCap Contributor
- Reviewers have to learn how to use Contributor (this is often the most significant barrier to uptake).
- You have to install and maintain Contributor on all reviewers' computers.
- You have to pay for licences if you need reviewers to add or change content. With an unlicensed copy, reviewers can only add annotations.
Contributor review workflow
In a nutshell, a Flare author sends a package of topics to a reviewer who accepts or rejects changes and adds their own annotations and new changes. The package is then returned to the original author who accepts or rejects the reviewer’s changes and incorporates the changed topics back into the project.
In the following sections I’ve written some guidance and tips on each of the main stages within the workflow.
Stage 1: Select files for review
You can select the topics in Flare using either the Content Explorer, File List, or TOC (see screenshot below). After clicking Send for Review, the topics are zipped up along with any necessary linked files such as stylesheet, images, and variables into a Review Package with a .fltrev extension.
The advantage of selecting from the TOC is that the full TOC is included within the Review Package, enabling reviewers to see the context of the topics within the documentation set.
Stage 2: Make the Review Package available to the reviewer
You can do this using the Send Files for Review Wizard in Flare, which enables you either to email the Review Package or to save it to a shared drive.
Stage 3: Reviewer reviews the topics
The reviewer opens the Review Package in Contributor, and can then add annotations to each topic. With a licensed copy of Contributor they can additionally accept or reject changes, and add their own content.
Stage 4: Reviewer makes the edited topics available to the original author
The reviewer can do this either by emailing the Review Package back to the sender, or by saving it to the shared drive.
Stage 5: Import the Review Package into Flare
This creates a copy of the Review Package within the Project Folder of the original Flare project. The topics contained in the Review Package are displayed in the File Reviews Inbox.
Stage 6: Accept or reject changes made by the reviewer
Open each topic from the File Reviews Inbox, and accept or reject changes as appropriate. The original Review Package outside of the project is unaffected, and can be retained for audit trail purposes.
Stage 7: Accept the topics back into the Content Explorer
As a result of accepting the changed topics, the original topics are over-written with the revised topics from the File Reviews Inbox. If the original topics have been edited since sending out the Review Package, Flare enables you to merge the two sets of changes.
If you have any experiences of using Contributor, I’d be interested to hear from you. Please email me on matthew@uaeurope.com.
