MadCap Analyzer

My apologies for commiting the cardinal blogging sin of not posting, but four major projects hit me simultaneously in October and something had to give. Three of those projects are now history and the fourth is almost done, so I can start blogging again...

MadCap Flare is a powerful and feature-packed product, but it's long been deficient in the area of project reporting - the ability to report on such things as the styles used in the project, topics that have not been listed in the index, and so on.

MadCap recently corrected this deficiency with its release of Analyzer. Analyzer is a surprisingly powerful utility that can parse a project and then create reports listing the results, and even suggest improvements to the project.

Analyzer analyzes your project (sorry...) and provides a summary of various issues like the number of topics that have not been added to the table of contents or index, the number of styles in the CSS that have not yet been used (suggesting that they might not be needed in the CSS at all), and so on. Double-clicking an entry in this summary opens a separate window that presents more details about that issue and lets you correct the issue in Analyzer or in Flare (or the forthcoming Blaze).

Analyzer provides a lot of useful information about a project and can be considered the Flare (and Blaze) equivalent of RoboHelp's Reports feature (on the RoboHelp Tools menu). More specifically, Analyzer lets you look at TofC and index entries, variables, snippets, styles, and more. It also flags developer errors, such as undefined styles, variables, glossary entries, and other features that are easy to accidentally leave unfinished. A nice touch is the Replace Local Style Suggestions feature, which flags places in the project where you used local formatting and suggests replacements from the CSS.

Like any other v.1 software, Analyzer has some problems. I ran it on a mid-sized (~700 topic) Flare project and found one apparent problem and one surprising omission:

The problem is the length of time Analyzer took to do the initial analysis of the Flare project, which it has to do before any other Analyzer functions can kick in. It took about five minutes to analyze my topic project. Without any baseline, I can't say whether this is slow, fast, or normal, but it seemed slow.

The omission is the inability to create a simple list of topics in the project. This is a very useful feature, at which RoboHelp excels, because it makes it easy to create project task checklists. For example, let's say you imported an old WinHelp project into Flare and need to look for and fix the style class on the popups. How do you keep track of which topics you've checked? You can just open Flare's File List, which lists the topics alphabetically, and work your way down the list, as long as you don't need to make marginal notes about some topics. A printed, alphabetic list of the topics is a lot more useful. Surprisingly, there's no way to do that in Analyzer *through the interface* or in Flare itself.

There is one way around this omission. It's not perfect, but it's better than nothing. Thanks to Ryan in tech support for suggesting this trick...

One of the reports that Analyzer offers is "Topics Not In Any TOC." So the trick is to temporarily remove all TOCs from the project, which means that, technically, none of the topics are in a TOC and will thus appear on this report. You then generate and print the report, then put the TOCs back into the project. To do this:

1. In Windows Explorer, open the ...Project/TOCs folder under the project folder and change the name of each TOC from .fltoc to .oldfltoc or something like that. The name change makes Flare "lose" the TOCs, which thus means that none of the topics are in a TOC. (Open the TOCs folder on the Project Organizer tab and you'll see that all your TOCs are gone.)

2. Go to Analyzer and run the Topics Not In Any TOC report.

3. Change the names of the TOCs back to the original fltoc extension.

4. Close the project in Flare, then re-open it, to restore the listing of your TOCs in the TOCs folder on the Project Organizer tab.

The flaw in this trick is that it is a work-around that requires you to go behind the interface in Flare. But it does work. The drawback is the fact that this trick can't generate an alphabetic list of all the topics in the project. Instead, it generates an alphabetic list of all the topics as they're listed in each folder and sub-folder on the Content Explorer tab in Flare. This means that you can't just scan down the list to find a topic, but instead have to know what folder to look in in the first place. It's not that difficult if you know your project, but it is inefficient.

In summary, Analyzer is fairly inexpensive - regularly $299 but currently available at the promotional price of $199, at a discount for Flare maintenance customers, and free for MadPak maintenance customers. It offers a level of project analysis and reporting that's been sorely missing in Flare, and I recommend it highly.