MadCap Software LogoLeft Quotation MarkRight Quotation Mark

MadCap Flare 9 Review by Matthew Ellison

Download Article
MadCap Icon

Introduction

intercom March 2013 cover

MadCap Flare is a mature, single-source authoring tool that has evolved an impressive feature-set over the years since its initial release back in 2006. Given the fact that MadCap Software has significantly revised and added to each subsequent new version based on user requests, it is perhaps not surprising that the product has now reached a point where the core functionality requires very little revision. With most of the core functionality already taken care of, MadCap Software has taken the opportunity with version 9 to focus on the specialized needs of specific groups of users, such as those who require press-quality print output or authors who need to publish in right-to-left languages such as Farsi or Arabic. MadCap has also reacted to the current explosion of interest in social networking by completely revising its implementation of user commenting and feedback.

When you first open Flare 9, you could be forgiven for thinking that nothing has changed at all from previous versions. I actually like the fact that MadCap has resisted the temptation to tamper with the basic interface, which was radically revamped around a ribbon-based workspace in version 8 and which works well, in my view. Beneath the surface, though, there are a number of significant enhancements to existing features and a major new option that enables you to create a social layer around your documentation. The impact of these changes won't be felt by all users of Flare—as I mentioned in the opening paragraph, many of the new and revised features address special use cases. In my survey of the new and changed features below, I have ranked the items by taking into account not only the significance of the change but also the extent of Flare's user base that I believe may benefit from the change.

New Socially Enabled Output

Since the launch of Flare 3.0 in 2007, MadCap has offered the option of enabling user feedback and commenting in any of the HTML-based outputs. This was available either through a hosted subscription service (MadCap Feedback Service) or an “on-premise” server product (MadCap Feedback Server) for which a separate license fee was payable. With the release of Flare 9, these two options have been replaced by a brand-new, on-premise server product called MadCap Pulse. This is the result of a partnership between MadCap Software and Neudesic, maker of the enterprise social collaboration software Neudesic Pulse. MadCap Pulse provides almost all of the functionality that was previously offered by Feedback Server, but it goes further by enabling documentation authors, end users, and other stakeholders to collaborate in a far richer and more flexible way.

Figure 1. Help topic showing comments and contributions enabled
Figure 1. Help topic showing comments and contributions enabled by Pulse

The idea behind Pulse is to add a social layer around your documentation, creating a real-time community that enables users to ask questions, express opinions, engage with other users, and share information (see Figure 1). Some of the new features available with Pulse include:

  • Groups: it is possible to create discussion groups around particular documentation topics or themes. Specific users can be invited to participate within each group, and this provides a great way to generate useful comments and feedback, as well as engaging users more actively in your documentation.
  • Tags: all users can assign their own tags to any comments, and they can then search on these tags (in addition to being able to search the comment content).
  • Sharing: there is support for uploading and sharing a wide variety of content types (including images and documents).
  • Tasks: it is possible to assign tasks and responsibilities to other users. This could be useful internally for assigning responsibility for reviewing or editing tasks to other members of a documentation team.

It will be interesting to see the extent to which users embrace this kind of documentation-centric community. My own view is that it may not completely remove the need for other types of user-to-user forums, particularly for users of software. These people may still wish to post questions on an unstructured user forum rather than search for an appropriate topic within the documentation to which they can post their comment.

Figure 2. Sample report from Pulse
Figure 2. Sample report from Pulse

Previous users of Feedback Server should note that Pulse has the following restrictions: it cannot be used with the HTML Help (.CHM) output format and it does not permit the user's comments to be reviewed by an administrator before they are visible to other users. So you have to be comfortable with the fact that once users have been registered they are free to publish immediately any comments they like. Having said that, administrators will have the power to delete any content such as offensive comments.

If you want to take advantage of this new option for socially enabled documentation, you will need to take out a 6- or 12-month subscription for the Pulse product. Subscription fees will be based on the number of users who sign up to the community. This puts collaboration and feedback within the reach of small organizations with relatively few users, who may not have been able to previously afford the fixed-license fee for Feedback Server However, it may result in higher costs for major software companies with very large numbers of active users of their documentation.

Once you have subscribed to Pulse, enabling the community features for any HTML5 or WebHelp target is simply a matter of entering the URL for the Pulse Server location on the new Community tab within the Target Editor. This tab replaces the Feedback Service tab in earlier versions. Administrators can log on to a special interface to the Pulse Server product in order to perform administrative tasks such as creating groups, deleting files, and producing a range of different reports on the usage of the documentation and its social layer. These reports can potentially provide great insight into the views, needs, and behavior of users of the documentation. Figure 2 shows a sample report.

Enhanced Print support

Although Flare is perhaps known primarily as an authoring tool for creating screen-based user assistance, many authors are also using it to publish print-based outputs such as PDF. Indeed, MadCap Software has told me that some of its customers use Flare for generating print-based outputs exclusively and have no need for the HTML-based formats. Apparently there is a trend toward the blurring of roles between content authors and graphic designers, and authors are now seeking a new breed of tools that enable them to manage content effectively as well as providing rich and flexible control of page layout and formatting. With this in mind, MadCap has enhanced the print support in Flare 9 and introduced a number of features that you might have previously expected to find only in a specialist page layout or desktop publishing tool.

Perhaps the most significant of the print enhancements is the new support for the CMYK color model. In previous versions of Flare, color values had to be expressed as RGB values, which is fine for on-screen presentation since computer displays create color by combining red, green, and blue pixels. However, commercial offset printing typically uses separate plates for Cyan, Magenta, Yellow, and Key (black), and therefore uses the CMYK model. In Flare 9, you can now specify any color (for fonts, backgrounds, borders, etc.) using a CMYK value, thus ensuring that the color is printed exactly as required.

Other print enhancements include new options for including crop marks and registration marks on print-based output and a number of miscellaneous improvements to Print Layouts. As a result of all these enhancements, authors are much better equipped to produce high-quality, full-color, printed documentation directly from Flare without needing to involve a specialist page layout tool in the publishing workflow.

Figure 3. Enhanced Index tab in HTML5 skin
Figure 3. Enhanced Index tab in HTML5 skin

Enhanced html5 Skin

One of the headline features of the previous release of Flare (version 8) was a new browser-based output type that exploited some of the new features of HTML5 and CSS 3. This output type called HTML5 was technically and aesthetically a huge advance on the older WebHelp format, but it was marred by some curious limitations: it did not provide highlighting of search results and, more significantly, its Index tab had no text-entry box. This meant that users had to scroll through the index to find specific entries. This latter limitation made long indexes viewed over a Web connection almost unusable and, as a result, I have reluctantly had to advise some Flare users against migrating from WebHelp to the HTML5 format.

I am pleased to say that both these issues have been addressed in Flare 9. Indeed, the Index tab in the HTML5 skin is now more powerful and easier to use than the old WebHelp index. There is now a text input box at the top of the index—as you type, the index is filtered automatically to show only the top-level entries that contain matching text in any position. The fact that it matches text in any position within the index entries means that there is no longer a need to add multiple entries with the same words in a different order, and this may reduce the indexing time and effort required. Another enhancement is that sub-keyword entries are initially collapsed (hidden), which makes it easier to scan through the list of top-level entries shown. Figure 3 shows the index entries displayed as a result of typing “colo,” with sub-keywords collapsed under the top-level entry of “color.”

Search highlighting (with a toolbar option that enables users to turn it off) is now fully supported in the HTML5 output. There is now also a text-input box on the Glossary tab that enables users to quickly locate specific entries. All these changes are most welcome, and mean that the HTML5 target type is now a very attractive and compelling alternative to WebHelp.

Figure 4. Sample advanced condition expression
Figure 4. Sample advanced condition expression

Advanced Condition Expressions

In the Help topic that describes what is new in Flare 9, “Advanced Condition Expressions” is not listed as one of the major new features. However, I consider its impact to be potentially more widespread than that of any of the other changes in Flare 9. After all, the vast majority of authors will be using Flare to do some sort of single-sourcing, and conditions frequently play a critical role in the success of this process. In Flare 9, you assign conditions to content in the same way as in previous versions (except that there is now a useful Conditions option on the context menu displayed by right-clicking in the XML Editor). The significant change is in the way you can now specify which of these conditions is included or excluded within any given target. Previously, you could only choose either to include or exclude each of the available conditions; this restricted the combinations of conditions that were achievable and also led to unwanted results and some confusion when two conditions with conflicting include/exclude instructions were applied to the same content item. In Flare 9, you have the new option of using a Boolean expression to combine your conditions using and, or, and not operators. This offers far more control over the selection of appropriate and relevant content for any given target and opens the door to a range of new and more sophisticated single-sourcing scenarios. Figure 4 is an example of the kind of complex condition expression that is now possible. This expression includes content that has Website and All Print conditions applied to it, but specifically excludes content with the PDFA condition.

Text Editor Enhancements

Most Flare authors will create and edit their content using Flare's XML Editor that presents a very accurate WYSIWYG view of each topic. An alternative, however, has always been to edit the source XML code directly using a text editor. Until now MadCap has provided only basic support within the user interface for doing this, and if you opened the same topic in both the XML Editor and the Internal Text Editor then these two views were separate and independent of each other—any changes made in one view were not reflected in the other view until you saved the topic. What's more, using the Internal Text Editor was always a laborious and error-prone business because you had to type all the code by hand and there was no real-time syntax checking. Flare 9 now provides far better support for editing source code: there is an Auto Complete option that speeds up the entry of XML tags and you are alerted immediately if you enter code that breaks the required XML syntax. The Text Editor (which shows the source code) is now fully integrated with the XML Editor so that typing or selections made in either view are simultaneously shown in the other view. You can choose which of these views you wish to work in and there is even an option to select a split view that shows the Text Editor and XML Editor side-by-side (see Figure 5).

Despite these considerable enhancements to the Text Editor, editing raw XML code is still not for the faint-hearted and I anticipate these enhanced features being used by only a minority of more technically minded Flare users.

Figure 5. Text Editor and XML Editor shown in split view
Figure 5. Text Editor and XML Editor shown in split view

Free Capture integration

MadCap Capture provides powerful and flexible controls for capturing and annotating screens. Although a separate tool in its own right, it is tightly integrated with Flare in many different ways. For example, you can capture screens from Flare using Capture's functionality but without necessarily invoking the full Capture interface. It is also possible to use variables defined in a Flare project within the text callouts in Capture. Capture has previously attracted its own separate license fee, which meant that Flare users who decided to avoid this additional cost were missing out on useful functionality. With the release of Flare 9, Capture is now bundled as a free product.

“Flare 9 contains a range of impressive and well-executed new features. The most significant of these, the option to add a social layer to HTML-based output, is available if you subscribe to the new server product, MadCap Pulse.”

I am pleased that MadCap Capture is now available to all, because it is required for a very welcome new enhancement to Flare's FrameMaker import process. When you import images in a FrameMaker frame with text callouts, the callouts are now converted to XML code within a properties (.PROPS) file for the image. This means that, following the import, the text callouts can be subsequently edited, moved, or redesigned using MadCap Capture.

Right-to-left Language Support

This is a great example of an enhancement that is highly significant, but only to a relatively restricted set of users. It has previously not been possible to create or publish content in right-to-left languages such as Arabic or Hebrew using Flare, but Flare v9's XML editor now supports the displaying and editing of right-to-left language text correctly. You also have the option to automatically reverse appropriate style sheet rules (such as right and left margin settings) and Page Layout settings.

Other Miscellaneous Enhancements

There are many other enhancements within Flare 9 that add refinements to the product's functionality or make it easier to use. An example of a minor, but useful, improvement is usability is an extended context menu, displayed by right-clicking on a folder within the Content Explorer. This now contains options for adding new files of any of the standard content types (topic, image, snippet, master page, etc.)—previously it was possible to add only topics and folders in this way. Another example is the new Character dialog that makes it easy to insert any desired symbol or special character from any of the fonts installed on your computer. Previous versions of Flare provided a very limited selection of symbols and any other symbol had to be copied from a third-party editor.

Other new features include:

  • A new plug-in API that lets you integrate Flare with DLLs that you produce. This means that you can potentially add your own customized ribbons, menus, or toolbar buttons to Flare if you have the necessary programming skills.
  • The ability for Office 365 users to import Word documents without requiring the full version of Word to be installed.
  • Support for the Secure FTP protocol when publishing output to a server.
  • Enhanced support for spelling and hyphenation dictionaries—it is now easy to see which dictionaries you already have installed and to download dictionaries for new languages.

It is also worth mentioning that the EPUB output type has been upgraded for EPUB3 and now offers options for validation of the output and for generating MOBI output for viewing on a Kindle.

One feature that I had expected to find, but is not present in this version, is a mechanism for automatically adapting to a range of different screen sizes (from smartphone to desktop) within a single target. Although Flare does a great job of providing specialized targets for mobile (WebHelp Mobile) and for desktop (WebHelp or HTML5), there is no support for publishing to a single URL that redirects to the appropriately formatted content based on the user's screen size and browser agent (unless you code such a portal page yourself). I was surprised at this omission, since it is a feature that rival product Adobe RoboHelp has made much of in its most recent release, and responsive design is becoming an increasingly hot issue.

Conclusion

Flare 9 contains a range of impressive and well-executed new features. The most significant of these, the option to add a social layer to HTML-based output, is available if you subscribe to the new server product, MadCap Pulse. Many of the other new features, such as right-to-left text and the text editor enhancements, address particular use cases and will be of great value specific groups of Flare users. The lack of a unified target that can adapt to a range of different screen sizes is an issue that I would expect to be addressed in a future version.

In my view, the two areas of change in Flare 9 that will add most value to the greatest number of Flare users are the much-needed enhancements to the HTML5 skin (including the all-important ability for end users to access index entries directly by typing) and the ability to create advanced condition expressions. I consider it worth upgrading to version 9 for these changes alone.

MATTHEW ELLISON (matthew@uaeurope.com) is an independent consultant and trainer with 25 years of experience in software user assistance. Based in the UK, he is technical director of the annual UA Europe conference www.uaconference.eu. Matthew is a MadCap Flare Certified Instructor, and a past winner of the prestigious Horace Hockley award that is presented annually by the Institute of Scientific and Technical Communicators (ISTC).