First, a bit of background. MadCap Software is the developer of Flare. It originated from another famous online help tool development company, eHelp, formerly Blue Sky Software, which made RoboHelp. After Macromedia bought eHelp, support for RoboHelp eventually stopped. Later, in the world where the big fish continually consume the smaller, Adobe, perhaps the biggest fish of all, bought Macromedia, acquiring RoboHelp, which is still available today.
Mike Hamilton was the Product Manager for RoboHelp since these early days. After the takeover, he, along with many of the other eHelp developers, left the company to join a new one, MadCap Software. Mike is now the Vice President of Product Management there. I had the pleasure of seeing him present his “RoboHelp killer”- MadCap Flare - at our chapter meeting in March of 2007. It was a compelling presentation of a brand new online authoring system, designed from scratch, with many impressive features. He also provided invaluable help when I was first learning this product.
Early in 2008, my company had acquired several licenses for Flare 3.1. We were looking to replace WebWorks Publisher 7 (WWP), the tool we used to generate online help from our FrameMaker files. It's a solid program, but not the most user friendly, to put it mildly. To make certain changes, you have to know how to edit scripts, macros, text-based configuration files and XML. In other words, you have to be a rocket scientist disguised as a tech writer.
Initially, I was very impressed with Flare. Although it's a complex program, with a bit of a learning curve, the program's interface is generally sleek and well-designed. Unlike WWP, you don't have to edit configuration files. Unfortunately, I encountered many problems which I will describe here. I admit some of these are minor quibbles, but many are serious enough to preclude me using this product at this time.
I'll start with what I encountered when imported the FrameMaker files into Flare:
- The process of importing FrameMaker files into Flare is fairly straight-forward. Most of the work is done in the Frame Import Editor screen. To ensure that your Flare project stays linked to your FrameMaker files, you have to select the following option in the Frame Import Editor > Source Files tab:
What's confusing is that there is another check box, on a completely different tab, that also has to be selected. It's on the Frame Import Editor > Options tab:
Finally, there is a third check box, on a completely different screen (the Basic tab of your target's properties) that also has to be selected!
- In the Frame Import Editor > Source Files tab, the FrameMaker files and books that you imported are listed. Unfortunately, you can't resize the FrameMaker Files column, so if you have a long path, you won't see the name of the file:
- In the Frame Import Editor > Stylesheet tab, you click the Conversion Styles button to open the Import Styles Editor dialog box. Here you can specify how to convert each property of the FrameMaker styles. The Preview section, which should display how the style looks, does not work. No matter which style you select, the same "no preview available" message appears:
- Similarly, in the Frame Import Editor > Paragraph Styles tab, the Preview box does not display a preview:
- The main area you work in is the Project Manager. It includes conditional text settings, your imported files, your Flare "skins" and your targets, which represent your generated help file or target. I found it confusing that both skins and target settings control the appearance of the final output, and found myself moving back and forth between these two areas many times to find the setting I needed.
- Another area you may work in is the Content Explorer. This contains links to each generated HTML file, and to your stylesheet. For some reason, two stylesheets are listed here (template.css and template1.css) although only one can be active.
- Flare's stylesheet editor is quite powerful. There are two views: Simplified and Advanced. The Advanced view allows you to further fine-tune your various styles. In the Simplified view, you can view and even change more than one style at once:
There are some problems when editing individual styles. For example, when applying bold, superscript, subscript or small caps to the font of a style, the Preview box doesn't show the changes:
- After setting up the template, I generated the project to produce WebHelp help project files. The generation time was quite long, certainly longer than WWP.
The remaining problems described next occurred in the generated content. - In the table of contents, some of the headings were missing words:
Specifically:- Roles in should be Roles in IStream Writer.
- Understanding Elements should be Understanding IStream Writer Elements.
- Documentation should be IStream Writer Documentation.
The problem is caused by the fact that IStream Writer is actually a FrameMaker variable. I've confirmed with MadCap that Flare has trouble processing variables. As a result, variables in headings will not appear in the TOC headings. Also, in some cases, in the text itself, spaces that follow the variables are missing, causing the words to run together. Here, for example, the word Writer is a variable, and the space after it has been removed by Flare:
- There were problems rendering graphics properly. In our documents, we use large, high quality graphics so that they will display well in our PDFs. The size is scaled down within an anchored frame. Obviously, we don't want the original size showing in the help files. There's an option in the Frame Import Editor > Options tab that is supposed to retain the image size you've set in FrameMaker:
Unfortunately, this check box has no effect in the current version; the image will appear in its original, oversized dimensions. This problem has been somewhat addressed in the next release, version 4, which I was able to receive as a beta. In this beta, the image is now at the correct size, but the quality is very poor. MadCap tech support stated that this is because of the way Internet Explorer scales down the image, therefore claiming that it's the browser's fault and not Flare's. However, WWP renders the images correctly, at a good quality and at the correct size.
To resolve the graphics problem, MadCap suggested that we resize all our graphics to improve the quality, which is not an acceptable solution. First, there are thousands of these files, so it would take a long time. Second, we want the image size to remain high for our PDF outputs. Finally, even if we could fix the graphics, the text callouts around the graphics also render poorly.
I wanted to include a screenshot that would indicate the poor image quality, unfortunately, now the graphic is completely grayed out, even after doing a full regeneration. You can still see, though, that the text callouts are rendered poorly:
I admit that other graphics have fared better, but I can't explain why this particular one has vanished. - The Browse buttons don't navigate you in the order of the topics, but instead in the sequence in which you've browsed the topics.
Because users can already use their browser's forward and back buttons to view the topics in the order that they had browsed the topics, there is no reason to duplicate this functionality. In WWP, the browse buttons correctly move users through the sequence of topics as they appear. MadCap has told me this has now been logged as a defect. - I had problems getting the numbers to line up – see how the number 10 is improperly aligned?
The number 10 should be slightly over to the left so that the decimals line up. Also note again that there is no space between the word The and IStream Writer, because IStream Writer is a FrameMaker variable. - Another major problem with Flare is that there is no effective table management. FrameMaker's table styles do not appear in the table styles portion of the stylesheet editor. Instead, many different numbered td.Cellclass styles appear:
It makes no sense to have dozens of td.CellClass styles being generated, and there is no way to know which one applies to which table throughout the document. There should be a one-to-one mapping of FrameMaker tables to Flare styles, as WWP does.
MadCap Flare has tremendous potential, but suffers from problems that are all too common in the software industry: it tries to do too many things, and in the process, falls short for specific tasks. I'm hopeful that all of these problems will be addressed in a future release.
In the meantime, if you're looking for a solid, mature, dependable tool to generate online help from FrameMaker, stick with WebWorks Publisher, which is now called e-Publisher.
Update: I submitted this review to Mike Hamilton, but have not heard back from him.
