Madcap Blaze's Topic Review Feature: A First-of-a Kind Feature with an Interesting Workflow

by Tom Johnson on Apr 24, 2008
categories: technical-writing

Blaze is a new Framemaker alternative that Madcap Software has just released into beta. With Blaze, you can create printed documentation and publish it to Word, Framemaker, PDF, XPS, and an XHTML book (but not webhelp).

When I first heard of Blaze, my immediate question was — Doesn't Flare already publish to Word and FrameMaker? If so, why would I need Blaze?

The short answer is, you don't need Blaze if you already have Flare. But if for some reason you only write printed documentation, and never online help, then Blaze might be for you.

Despite the irrelevance of Blaze for my project needs, Blaze does have a new review feature that is unique and worth exploring. As you know, you often you need SMEs and other team members to review your content. When your content is trapped inside a help authoring tool, you can't quickly send SMEs a file to review — how could they open it? As a result, we traditionally publish our help to Word or PDF, print it out, and then stick it on the SME's desk.

However, in many cases getting a SME to review 100+ pages of documentation is a battle. Like most people, they're busy. Reviewing something takes times. Writing is often not their expertise or interest. So, you know the story. Either it never gets reviewed, or it gets reviewed tenuously.

With Blaze, Madcap offers you a totally new review workflow. You send a topic to a SME for review from directly within the Blaze interface by going to File > Review > Send for Review. When you do that, the following dialog box appears.

Selecting the "Allow Reviewers to edit content" check box gives the reviewer control to make changes to your text. If you clear this check box, the reviewer can only insert annotations.

After selecting your options, Blaze packages up the topic with a stylesheet and any relevant images and puts it in a .bltrev file. In the same step, it initiates an email handler that interfaces with Microsoft Outlook to create a new message with the file attached. It then sends the file to the email recipient you selected.

But how does the SME open a .bltrev file? Here's where X-Edit Express comes in. The SME downloads this free application (requires .NET 3.0 as well, if not already installed). When the SME then double-clicks the .bltrev attachment, it opens in X-Edit Express. The SME can then insert annotations or make direct edits to the content.

Note that X-Edit Express only allows you to edit and annotate existing content. If you want the SME to actually contribute new files for your project based on a template, you'll need X-Edit (which isn't free), and the review process is slightly different. But the workflow of sending an attached file back and forth through email is still the same.

After the SME finishes reviewing your topic, he or she clicks Return to Sender (an option within X-Edit Express) and the email handler pulls up Outlook and sends the file back to the author, i.e., you. When you double-click the attachment, you're prompted to add it back to your Blaze project with the following dialog box.

The email handler then saves it in a special inbox folder that Blaze recognizes.

As an author, you open Blaze and go to File > Review > Topic Reviews. A Topic Reviews pane appears on the left with a filter at the top (the pane is similar to other panes, such as the Content Explorer or Project Explorer). In the filter, select Inbox, and you'll see the SME's review, with the edits or annotations. As desired, you can choose to accept the reviewer's edits and overwrite the original.

Accepting annotations is different from accepting edits. If you accept the annotations, they're added to the topic, but rather than appearing within the topic's text, they appear in an Annotations pane to the right. When you select one of the annotations in the Annotations pane, it highlights the word related to the annotation. Kind of neat there.

Overall, I like the topic review, but I'm not thrilled about the idea of sending attached files back and forth over email. It feels too 1995-ish.

In contrast, a centralized review from a wiki-type editor makes much more sense to me. But I can see how implementing this would be difficult. Blaze would need to have wiki-like features, and require a database. Topics would need to be editable through a browser. And you would need a mechanism that prevented simultaneous overlapping edits. Maybe that's what Team Server is about — I don't know.

Still, the idea of sending one topic at a time to a SME for review may prove interesting. And the movement of files through email is relatively slick (if you have Outlook, that is. I have a clunky old email program called GroupWise that has some hiccups with Blaze email handler). Sending a topic for review is not as strenuous as manually attaching files to messages.

But here's my question: If your project has 200 topics, does that mean the SME gets 200 emails from you to review? Yes, that's how it currently functions. You can only send one topic to review at a time. In many ways, this makes the topic review feature less useful. The idea, however, is to send topics to the SME to review as you finish them, rather than in one big whallop near the release deadline. That workflow may actually prove to be more efficient.

Although I've limited tmy discussion to reviews by SMEs, I can see how a topic review would be helpful for team authoring. If you have a contractor, intern, or other assistant, the topic review provides them with a way to author content that you can add to your help project with relative ease.