Flare 7—Something for Everyone

By Ed Marshall | Associate Fellow

Flare 7 is the latest version of the state-of-the-art help authoring tool produced by MadCap Software. It has several new features and enhancements, which I’ve categorized in Table 1.

Table 1. Flare 7 Features and Enhancements

Category	New Features/Enhancements
Adding smart device technologies to traditional PDFs	Support for QR Codes in PDFs.
Accessibility	Several enhancements make it easier to provide accessible features in Flare output.
Workplace collaboration	The following collaboration/source code control tools are now supported: Microsoft SharePoint Microsoft Team Foundation Server 2010 Subversion (a popular free source code control tool) Additionally, there is a new consolidated tool, MadCap Contributor, that non-Flare users can use to add comments or edits to your review drafts from Flare. In keeping with MadCap’s dedication to integrating all their products, you can easily incorporate reviewer’s comments into your Flare project (similar to Microsoft Word’s Track Changes features). You can now add external files to your Flare project. The original files stay in their original location. All you need to do is synchronize the file in Flare with the version in the source location to have the current version in your Flare project.
Productivity	The Alias Editor used for context-sensitive help was greatly enhanced. Many new reports were added and the reports were categorized for ease of selection. A new technology, called Auto Suggestion, was added to detect text already in your help project and suggest possible matches that can be reused. You can now set more precise scan options in the built-in Analyzer of Flare. Some new reports were added also. The add-on MadCap Analyzer ($299 retail price) is an invaluable tool for scanning and suggesting often-used text that can be defined once and reused in your Flare project. A new button on the toolbar makes it easier to create/insert Variables. A new button on the toolbar makes it easier to create/insert Snippets. There are three new options for importing projects. You can now import a RoboHelp project, an HTML Help project (HHP file), or a compiled HTML Help file (.chm). You can now specify how a link looks and acts. Improvements were made to the options for pasting non-Flare content into your Flare project. You can now select any defined target when you preview a topic. You can now specify the browser in which to open your WebHelp outputs when you generate any of the WebHelp targets. There is a new keyboard shortcut for formatting nested paragraphs in lists. It is now easier to remove inline formatting in your text.
Ease of reusing information	It is easier to specify an HTML Help file, or even a specific topic in a different help file to be included in your Flare project. It is easier to merge multiple HTML Help files. Enhancements were made to linking to MadCap Mimic movies and customizing the options for those links.
Making Flare’s UI more like other common tools (Microsoft Windows/Office)	Tables—several enhancements were added for creating, formatting, and editing tables. You can now hide/show columns from the column heading. More options were added for creating concept links. Document tabs can be moved by dragging them. Footnotes are now edited in the XML Editor window, not a separate window. The Home/End and Shift+Home/Shift+End keys now work as expected in Windows.
Google Chrome support	The Google Chrome browser is now supported.
Miscellaneous	Equation support was added. Vector graphics are now supported in PDFs.
Flare UI changes	Some buttons with text were replaced by buttons with icons. More options were added for creating keyboard links. A new keyboard shortcut to format nested paragraphs in lists was added. More options were added for creating and formatting related help topic links.

Adding the Power of Smart Device Technologies to Traditional PDFs

You can now insert QR codes into your content. QR codes are barcodes that can be read by mobile and smart devices. The barcodes can include text, URLs, email addresses, or text messages.

This new features leverages the support for mobile devices introduced in Flare 6. (Note, the author published a review of Flare 6 in the July/August 2010 Intercom.)

For example, you can include QR codes in your PDF documentation to provide links from your static PDFs to the latest downloads, patches, release notes, or updated docs from the PDFs. Users can then view or download the latest product updates/releases or documentation.

Accessibility Enhancements

Accessibility is an important issue that technical communicators need to consider. It’s not just being fair to users with physical challenges, it’s the law. The U.S. government requires that all products sold to government agencies be accessible to users with physical challenges. Common challenges include vision problems, hearing problems, and motor-skills problems.

Probably the easiest solution to implement for people with vision problems is to provide “alt-text” for components such as images, tables, mathematical equations, etc. Flare 7 provides an easy way to generate reports of components that are missing alt text as well as a quick navigation to the specified topics so you can make corrections.

To generate a report of accessibility issues with a Flare project:

Open your project in Flare.
Click Open Primary Target from the toolbar.
In the Target Editor pane, select Warnings from the left column.
Check the warnings you want to generate for your project.
Save your project.
When you generate your project, Flare will report any warnings selected in step 3. To generate your project, select MyWebHelp(Primary) in the Targets list of the Project Organizer, right-click and select Build ‘MyWebHelp’.
If Flare detects any warnings from the build, it displays them in the Errors tab:

One of the strengths of all of MadCap’s products is the tight integration of their applications, both within a specific application and across their family of products. For example, the screenshot shows three accessibilitywarnings from the build. You can easily go to the topic(s) listed in the report by clicking on each line in the Errors tab:

Once you have the reported topic displayed in Flare, you can correct the problem(s). For example, the first two entries in the report show that there are two images in the “Whats new.html” topic that do not have any alt text assigned to them. Alt text is text that describes images or other components to be spoken by screen readers used by those with visual difficulties.
Visually scan the topic for the two images. Right-click on the first image and select Edit Picture:

Note that there is no text in the Alternate Text field. Enter a useful description of the image in this field and click OK. It is a good practice to use helpful text in your alternate text. Repeat this step for the second image in this topic. Then, check all the other warnings about alternate text reported by Flare. (In this case, the icon is shown as a visual cue to the reader. Because the icon name precedes the icon in the text, you could either leave the Alternate Text field blank or enter something like “Image of the Preview Compiled Topic icon.”)

Workplace Collaboration Enhancements

Flare 7 supports the following workplace collaboration/source code control tools:

Microsoft SharePoint—Used by many large companies to share internal documents across groups.
Microsoft Team Foundation Server 2010—Another tool used by many large companies to share internal documents across groups.
Subversion—A commonly used and free source code control system used successfully by many smaller and mid-sized companies who cannot afford enterprise-level tools such as IBM ClearCase or Perforce.

Support for these three products shows that MadCap is aware of the needs of small to large companies and the tools being used by those companies. By supporting these products, MadCap addresses the needs of very small to global-scale companies.

The integration with SVN worked fine for me, though. The key information you need to know is the exact URL of the SVN server you are connecting to and, possibly, the port number on your machine. For those who tend to “set it and forget it,” you might need to talk to your SVN administrator or IT person to get that information. Once I set the URL correctly, the Flare integration with SVN performed quite acceptably, even over a remote DSL connection to the SVN server.

Note: I wasn’t able to test the SharePoint/Team Foundation Server integrations with Flare, as I don’t own or have access to those products. Feedback from other testers indicated these features worked well.

Additionally, there is a new product, MadCap Contributor, that replaces X-Edit, X-Edit Review, and X-Edit Contribute. MadCap Contributor consolidates the features of the earlier three products along with new enhancements to allow non-Flare users to review and comment on your content. You can then easily import those comments into your Flare content using the Review options in Flare (similar to Microsoft Word’s Track Changes features).

You can now add external files (such as logos, PDFs, etc.) maintained by other organizations to your Flare project. The original files stay in their original location and Flare makes local copies of them. All you need to do is synchronize the file in Flare with the version in the source location to have the current version in your Flare project. Once you add an external file to your project, it is very easy to embed it or create hyperlinks to it in your Flare project.

Productivity Enhancements

MadCap made many productivity enhancements:

The Alias Editor used for context-sensitive help was greatly enhanced.
Many new reports were added and the reports were categorized for ease of selection.
A new technology, called Auto Suggestion, was added to detect text already in your help project and suggest possible matches that can be reused.
You can now set more precise scan options in the built-in Analyzer of Flare. Some new reports were added also. The add-on MadCap Analyzer ($299 retail price) is an invaluable tool for scanning and suggesting often-used text that can be defined once and reused in your Flare project.
A new button on the toolbar makes it easier to create/insert Variables.
A new button on the toolbar makes it easier to create/insert Snippets.
There are three new options for importing projects. You can now import a RoboHelp project, an HTML Help project (.HHP file), or a compiled HTML Help file (.chm).
You can now specify format of links and their behavior.
You now have more options for pasting non-Flare content into your Flare project.
You can now select any defined target when you preview a topic.
You can now specify the browser in which to open your WebHelp outputs when you generate any of the WebHelp targets.
There is a new keyboard shortcut for formatting nested paragraphs in lists.
It is now easier to remove inline formatting in your text.

Alias Editor Enhancements

Flare 7 makes it much easier to create, customize, and debug problems with your context-sensitive IDs and numbers. The Alias Editor used to create context IDs/strings for context-sensitive help has the following new functionality:

Hide assigned identifiers—Displays only the context IDs that haven’t been assigned to a topic.
Generate identifiers—Creates context IDs for all the topics in your project.
Change identifier options—For example, you might want to set a prefix for your context IDs, such as starting at some number for a particular type of object, such as classes/interfaces, or use a standard prefix for dialog boxes, such as “dlg_” for all of them.
Identifier warnings—Lists unassigned identifiers.
Previous/next warning—Provides easy navigation through the warnings.
Locate topic in a header file—Highlights the identifier for the current topic.
Select a bookmark in the selected topic—Provides faster navigation to bookmarks within a topic.
Identify unassigned/assigned identifiers—Icons appear next to context IDs indicating whether they are assigned to topics or not.
Miscellaneous icon changes.

I was very impressed with this feature. It works very well. For someone who thought he was working smarter in the early 1990s, by creating Excel spreadsheets to track context-sensitive strings and numbers, this is so much better!

Reports Enhancements

MadCap not only added many new reports but also categorized them to make it easier for users to find and select the reports of interest.

The following shows the new categories and the specific reports in each category. New reports are bolded.

Table 2. Flare 7 Reports

Categories	Reports Available
Concepts—Markers that you use to tie several related topics together. Can be used as a Concept link for related topics.	Concept Links Files With Concepts Topics With Concept Links Topics With Concept Links Missing a Concept Used Concepts Used Search Filters
Condition Tags—Specifies content that only appears in some outputs. For example, text that applies only to printed output but not online output.	Applied Conditions Files With Condition Tags Undefined Condition Tags Unused Condition Tags Used Condition Tags
Content Files	Files With Changes (includes annotations) Files With Concepts Files With Condition Tags Files With Equations Files With File Tags Files With Glossary Term Links Files With Images Files With Keywords Files With Language Tags Files With Multimedia Files With QR Codes Files With Snippets Files With Variables Unused Content Files
CSH—Context-sensitive help features	Assigned CSH IDs Duplicate Map IDs Topics Linked By Map ID Topics Not Linked By Map ID Unused CSH IDs
File Tags—Often used to track projects by assigning authors or milestones to files.	Files With File Tags Undefined File Tags Unused File Tags Used File Tags
Glossary Term Links	Files With Glossary Term Links Undefined Glossary Term Links Used Glossary Term Links
Images	Files With Images Unused Images Used Images
Index	Files With Keywords Index Keyword Links Index Keyword Suggestions Topics With Keyword Links Topics With Keyword Links Missing a Keyword Used Index Keywords
Language Tags—Files that have a different language tag assigned to them. These files will use a pre-defined skin you created for that language instead of the language assigned to that project.	Files With Language Tags Used Language Tags
Links	Absolute Links Broken Bookmarks Broken Links Broken Snippet Links Concept Links External Links Index Keyword Links Topics Linked By Map ID Topics Not Linked Topics Not Linked By Map ID Topics With Concept Links Topics With Concept Links Missing a Concept Topics With Keyword Links Missing a Keyword Undefined Glossary Term Links Used Glossary Term Links
Multimedia	Files With Multimedia Unused Multimedia Used Multimedia
Project	Database Errors Files With Annotations Statistics
Snippets—Reusable text that can be longer than a variable, which is typically a word or string. Typically uses might be frequently used warnings or disclaimers.	Broken Snippet Links Files With Snippets Snippet Suggestions Unused Snippets Used Snippets
Styles	Duplicate Styles New Style Suggestions Replace Local Style Suggestions Undefined Styles Unused Styles Used Style Sheets
TOC	Duplicate TOC Items TOC—Primary Target Topics Not In Any TOC
Topics	Accessibility Suggestions Broken Bookmarks Markup Suggestions Non-XML Topics Topics Linked By Map ID Topics Not In Any TOC Topics Not In Index Topics Not Linked Topics Not Linked By Map ID Topics With Concept Links Topics With Concept Links Missing a Concept Topics With Keyword Links Topics With Keyword Links Missing a Keyword Unused Topics Writing Suggestions
Variables—An alias for a frequently used term. Typical examples include product name, version number, etc.	Files With Variables Undefined Variables Unused Variables Used Variables Variable Suggestions

MadCap provides a very comprehensive list of categories and specific reports that you can generate. It’s generally considered a best practice to have no errors/warnings in your help compilations, just as software developers follow the same practice with their code. MadCap shows their dedication to good software engineering practices and a broad knowledge of all the different types of technical documentation being created today by providing so many reports that cover a broad spectrum of technical communication. This is one of the enhancement areas in Flare 7 that led me to title this review “Something for Everyone.”

To generate reports:

In the Project Explorer, select Reports, right-click, and select Add Report File:
Initially, to create a new report from the predefined templates, select one of the subentries and click Add. The New Report page appears on the right.

The following shows the New Report page for the Links category, probably one of the most useful types of reports:
On this page, you can select any or all of the categories to be included in your report. Another productivity tip is to include a meaningful title for your new report in the Title field so you can easily identify it and use it later. It is very handy to check the Select all checkbox instead of scrolling through the long list of categories; then as an added convenience, check the Skip empty reports checkbox. This gives you only reports containing data—no empty reports to deal with.
To create your report, click Generate. Your report will appear in a frame below. To view your report more easily, click the Open in Browser button.

Optionally, you can save your report by clicking the Add to Archive button. Flare displays the Archive Report dialog with the Report Name pre-filled in:Note the nice touch of adding the date of the report in the Report Name field. To save your report, click OK. It will be saved with the new name in the Reports area of the Project Organizer.

New Technology for Suggesting Text Reuse

MadCap uses a new technology called Auto Suggestion to scan text as you enter it, check for possible matches in text already existing in your Flare project, and suggest possible matches. This enhances your productivity, reduces the possibility of inducing errors due to mistyping, and provides an easy way to provide consistent information across your project.

Finer customization is available in that you can add words/phrases to an auto-suggestions list. Auto Suggestion also will compare new text to existing snippets. Other fine-tuning is available, including excluding specific files from being used by Auto Suggestion or specifying the minimum number of characters to be typed before Auto Suggestion displays possible matches.

Ease of Reusing Information

You now can select an HTML Help file or a topic within a specified HTML Help file to be opened from a link in another help file.
Several improvements were made to linking to MadCap Mimic movies and providing additional customization of the options applied to those movies.

Making Flare’s UI More Like Other Windows Tools (Microsoft Windows/Office)

The UI for creating/formatting tables is much more like Microsoft Office table formatting. For example, you can convert text to tables or tables to text, very similar to how you do that in Microsoft Word. Also, it is easier to cut and paste rows/columns, either completely or just the text within them, and sort rows and columns, again similar to how you perform those tasks in Microsoft Office.
You can now hide/show columns directly from the column heading.
Additional control was added for creating concept links.
You can now drag document tabs right or left to change the order of tabs.
Footnotes are now edited in the XML editor, instead of in a separate window.
New Home/End key behavior—Pressing the Home key takes you to the start of the current line; pressing the End key takes you to the end of the current line. Pressing Shift + Home selects the text between the cursor and the start of the current line; pressing Shift + End selects the text between the cursor and the end of the current line.
A few buttons with text were replaced with buttons with icons.

Google Chrome Browser Support

Flare 7 supports the Google Chrome browser.

Miscellaneous New Features in Flare 7

You can now add equations to your help project. Flare 7 enables this through its support of the Mathematical Markup Language (MathML). MathML allows you to describe mathematical notations in XML.

Flare 7 supports vector graphics (EPS, PS, and SVG formats) for PDFs. The advantage to vector graphics is that they retain their crisp clarity even if you resize them.

UI Changes in Flare 7

Some icon buttons that had text on them have been replaced with buttons with icons on them.
You now have more options for creating and formatting keyword links controls. Keyword links are links that open related topics to the current topic, based on a shared index keyword that both topics have assigned to them.
You can now format nested paragraphs in lists by using the new Ctrl+ paragraph item shortcut. This has been a long-standing problem in Word-based help authoring tools.
You now have more options for creating and formatting related topic controls. Related topic controls provide links to related topics that you decided are related to the current topic.

Summary

Flare 7 provides several new features, improvements in making their UI consistent with other Windows programs, and offers uses choices in how they work in Flare. These include the following:

Adding QR codes to PDFs
Accessibility improvements
Productivity enhancements
Improvements in the ease of reusing information both from within the MadCap family of products and non-MadCap products
Support for equations
Support for vector graphics in PDFs
Continued improvements in making their UI more consistent with other Windows programs
Continued dedication to improving workflows within Flare and giving people choices in how to work in Flare

MadCap continues its best practice of providing a very complete, easy-to-follow, “What’s New in this Version” topic in the Flare help. I find this topic invaluable in learning how to use the new features in the latest version.

All in all, Flare 7 is a very solid, well-designed release from MadCap Software, with “something for everyone.”

A full-featured trial version of Flare 7 is available from www.madcapsoftware.com/downloads/?p=PFL. Note that trial versions randomly scramble characters to prevent people from deploying outputs to a shipping product. But the trial version has all the features of the full product.

Along with Flare, MadCap also makes several other tools that are completely integrated with Flare.

MadCap Capture is a very good, easy-to-use, screen-capture tool. A nice feature is that you can capture scrolling regions and then scroll in your captured image. I found this very helpful when I installed a buggy build at a client and got a long error listing in a CMD window. I used Capture to get an image of all the messages to send to the development team so they could diagnose the problem. I also used Capture to save the screenshots used in this article.

MadCap Analyzer is a very handy tool that will scan your Flare project and suggest improvements, such as repeated text that could be coded once as a snippet and reused as needed and variables (e.g., product names). So you only need to edit the snippet/variable once and the instances where it is included in your project are automatically updated.

MadCap Mimic is their offering for producing software simulations. They have several other tools, also. See www.madcapsoftware.com for those.

Thanks to Mike Hamilton (Vice President of Product Development), David Ferriot (Marketing Manager), and Rob Hollinger (Beta Manager) for providing a copy of Flare 7 to review and information on the new features.

Ed Marshall (ed.marshall@verizon.net) is an independent technical writing consultant and sole proprietor of Marshall Documentation Consulting (www.marshalldocumen tationservices.com), with more than 23 years of experience. He specializes in APIs/SDKs (application programming interfaces/software development kits), Web services products, and other types of documentation aimed at developers. Throughout his career, Ed has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching and replacing text in files. Ed is a popular speaker at a variety of professional development conferences, locally and nationwide. His previous appearances include events sponsored by STC, WritersUA, and DocTrain. He is an Associate Fellow of STC.

TagsTools of the Trade