Topic Reviews

Most authors require some kind of a process for others to review their Flare Desktop documentation, as well as to contribute new content when necessary. There are several ways you can do this, depending on your resources and knowledge of your reviewers and contributors.

Following are the most common methods, although you might use another solution not listed here.

Flare Desktop to Flare Online—Peer and SME Reviews

You can use the connection between Flare Desktop projects and MadCap Flare Online for topic reviews. Flare Desktop supports review packages (i.e., bundling files such as topics and snippets) and lets you send those packages to Flare Online to be reviewed by others. After editing and annotating the files in Flare Online's Review Editor, the reviewers submit the finished files, sending them back to your inbox in Flare Desktop. You can then accept or reject their changes and accept the file, replacing the original source file. See Flare Online Review Process.

Pros
It is an easy workflow.
You can send review packages that contain files such as topics or snippets for review.
You can bundle files along with a TOC node. This provides more context for content while reviewing.
SMEs do not need to download and install any software. The review takes place in the cloud.
Multiple reviewers (e.g., SMEs, authors) can make changes and add comments to the same topic or snippet at the same time.
A lightweight version of the editor means a streamlined interface. You only see options and features that are relevant to the review process.
Changes in the editor are auto-saved as you work. In addition, all changes are automatically tracked so the owner can easily locate edits for approval or rejection.
Files can be sent for review from a specific Git branch. This lets you keep reviews limited to files that are still in a state of development, as opposed to finished and ready for publication.

Cons

Although snippets that are part of topics can be included in the review (or excluded from it), you will need to communicate with your reviewers about them. You can tell reviewers to open snippets separately in Flare Online to provide edits and comments, or you can have reviewers insert comments above the read-only snippets in the topic itself. You might consider including larger and more substantial snippets as part of the review process, while excluding smaller snippets that you don’t feel need to be edited by reviewers.

Flare Desktop to Flare Desktop—Peer Reviews

If you need a fellow Flare Desktop author to review content, a convenient solution is simply for both authors stay within the Flare project. There are a couple of ways to do this.

First, the original author can communicate (verbally, via email, etc.), asking another author to review the file(s). The reviewer opens the file(s), tracks his or her changes (see Enabling Track Changes), and makes edits and/or annotations. The reviewer lets the original author know the files have been reviewed. The original author opens those files and accepts or rejects the changes.

A second way to use Flare Desktop for reviews between authors is to use the option in the Review ribbon to send files for review (in a review package). See Sending Files for Review in Contributor or Flare Desktop.

After the reviewer finishes and returns the files, the original author can view the tracked changes, accepting or rejecting them as necessary. That author can then click a button to accept a reviewed file, replacing the original file with the reviewed one. See Accepting Reviewed Files.

Pros
By keeping everything within Flare Desktop, there is no need to transfer changes manually or convert file types. It is therefore more automated than some of other review solutions.
Using a Flare Desktop-to-Flare Desktop workflow can work quite well if only one reviewer at a time is looking at a file.

Cons
If you need multiple authors to review the same files, those files will need to be “daisy chained,” reviewed by only one person at a time.
In order to see tracked edits, you need to click an option on the Review tab to show changes.

Flare Desktop to Contributor—SME Reviews and Contributions

If you need a SME—rather than another Flare author—to review content, MadCap Contributor is one solution.

For reviews, you send files to the person in a review package. That individual opens Contributor, which is like a scaled-down version of Flare Desktop. Changes are automatically tracked, and the reviewer can also add annotations, then send the review package back to you. After accepting or rejecting changes in those files, you can accept them back into the Flare project, replacing the original source files. See Review Workflow—Sending to Others.

For new content, the person using Contributor can create the content and send it to you. You can then accept the file(s) into your Flare project. See Contribution Workflow.

Pros
Because Flare Desktop and Contributor read the same types of files, there is no need to transfer changes manually or convert files. It is more automated than some other review solutions.
This solution can work quite well when only one individual at a time is looking at a file.

Cons
A SME will need to have Contributor installed locally.
Although it works similarly to many other editors, there are some new tasks that a SME will need to learn. Also, because Contributor is used for both reviews and contributions, there may be many more features and options in the interface than a person will need to use.
The process can get complicated if you need to have multiple people review the same file. The files will need to be “daisy chained,” reviewed by one person at a time.

PDF—Peer and SME Reviews

Another option for both peer and SME reviews is to generate PDF output and send it to whomever you need to review the content. The reviewer then makes comments in the PDF and sends it back to you. After this, you manually make changes to the Flare files based on the PDF comments.

Pros
PDF is a format that is familiar to most people.

Cons
Reviewers cannot edit the PDF. They can only add comments.
There is no way to automatically transfer feedback into your source Flare files. It must all be done manually.
You will need to set up the PDF output in your Flare project, if it is not done already. And even if it is already done, the entire output might be much bigger than the small section that you need the person to review.

Word—Peer and SME Reviews and Contributions

This option for peer and SME reviews is similar to the one for PDF. With this solution, you generate Word output and send it to whomever you need to review the content. The reviewer then makes changes or comments in the Word document and sends it back to you. After this, you manually make changes to the Flare files based on the Word document

Pros
Word is a format that is familiar to most people.
Reviewers can both make edits and add comments.
Word targets in Flare Desktop have an option that lets you enable the review mode for the output. This way, reviewers do not need to remember to enable the Track Changes feature in the Word document. See Enabling Review Mode in Word Output.

Cons
There is no way to automatically transfer edits or comments into your source Flare files. It must all be done manually.
You will need to set up the Word output in your Flare project, if it is not done already. And even if it is already done, the entire output might be much bigger than the small section that you need the person to review.

What the MadCap Documentation Team Does

We switch to the relevant branch and send topics and snippets to reviewers (authors or SMEs) as necessary. In addition, we limit the snippets that are included with reviews. It is more likely that we include larger snippets in a topic, while excluding many of the smaller snippets. We feel that including too many snippets as part of the review process can confuse reviewers, especially SMEs, who might not be familiar with snippets. So we communicate with reviewers to open and edit the snippets that we do include, but to insert annotations as necessary next to the read-only snippets that are excluded from the process.