RoboHelp 9 - Reviewing

Reviewing content has always been a significant task. RoboHelp 9 introduces two principal approaches:

• Peer Review - your fellow authors.
• Subject Matter Expert Review - your Subject Matter Experts and others.

Peer Review

RoboHelp 9 has a tracking feature similar to that in Microsoft Word so that you can see what has been added and removed. Both the initiating author and those reviewing can also add comments.

How it works

1. Each author, including the originator, sets the name they want to show against the edits in Tools > Options > General
   
   
2. Then turn on Tracking.
   
   
3. Make changes by selecting text and deleting it or by adding new text. As changes are made, the additions and deletions will be shown.
   
   
   The default colours can be changed but you cannot remove the underlining default, other than individually editing the changes. To change the colour, double click the edit.

4. The reviewer can also make comments, create callouts, highlight text and so on.

Simultaneous Changes

• Without source control, only one author can work on a project. So Author 1 would send the project to Author 2 requesting they review it, at that point Author 1's copy is frozen and is effectively an archive copy. Author 2 will on the project and return their copy to Author 1 who will then review the changes in that copy of the project. The process can be repeated with other authors if required but always only one person at a time.
• With source control the process becomes much easier. Authors would simply check out topics to comment and check them back in, signalling to the lead author that the changes have been made and are ready for review.

Printed Documentation

If you generate Printed Documentation, you need to clear all the tracked changes. Otherwise the insertions and deletions will be included but in the same format so that they cannot be distinguished from each other.

Subject Matter Expert Review

For reviews by SMEs and others who do not have Adobe RoboHelp 9, you can create a PDF review. Exactly how this works will depend on whether or not you have Technical Communication Suite with Acrobat Pro X, Acrobat Pro X as a standalone product or Acrobat Pro 9. The PDF Add-in is not sufficient, you must have one of the compatible full versions of Acrobat.

The screenshot below shows the options. We will look at them individually but first note that you can include / exclude topics using the checkboxes and you can filter by topic status.

Save locally

This will create a PDF on your local drive or a network location. You can then enable it for commenting using either Acrobat Pro 9 or Acrobat Pro X.

Send as e-mail attachment

This will create a PDF attached to an email in your default email client. The standard message indicates the reviewer will need to have Adobe Acrobat 9 or better to be able to comment. If they do not have Adobe Acrobat 9 or better and you do, then use the Save Locally option and then attach the PDF to an email.

Send for shared review

If you have Acrobat Pro X, either as part of the Technical Communication Suite 3 or as a standalone product, this option will be enabled. The dialogs that follow will allow you to upload the PDF to an internal server, to www.acrobat.com or to a Microsoft Sharepoint location.

• Provided the Enable Commenting in Adobe Reader option was ticked, the reviewer only needs to have the free Adobe Reader option.
• More than one reviewer can access the PDF simultaneously.
• They can be given a deadline.
• They can make their comments and edits across several sessions.
• The reviewers can make their comments using the tools available in Adobe Reader. They can add text, delete text, make comments, create callouts, highlight text and so on.
• When the review is complete, the reviewer clicks Publish.

It is vital that no changes whatsoever are made to the topics sent for review and you have to wait until all the reviewers have completed their review. The changes have to be amalgamated and processed in one process.

Reviewing the Changes

Peer Review

You can work through the topics and use the main menu or the context menu or accept / reject the changes. I found Accept and Move to Next did not always work as expected. In the example above after accepting the deletion of the first 32, I expected to move to the first 16. Instead it moved to the second 32, then back to the first 16.

Possibly that is a small bug but in any event I think the Review Pane shown below is a much better way to work. This is accessed from the Review menu or the View > Pods menu.

Subject Matter Expert Review

From the Review menu, you will import the PDF(s) so that they all appear in the Review Pane and then you start the process of acceptance / rejections. Double clicking any change opens the topic for you.

Gotchas

The PDF will not contain any dropdown or expanding text.

Conditional build tags will be ignored. All the content in the source topic will be included.

The topics will be in alphabetical order within the folders. The folders will be in Project Manager order. There is no TOC option.

Opinion

I've yet to try this in the real world but gotchas aside, it should be a very powerful addition. Reviewing has long been a painful process with many different workflows adopted by authors. Now there is a method that allows the changes to be accepted mostly with a click. Much less painful than the older methods.