By Paul Pehrson
It’s that time of year again, and just in time for MadWorld Conference, MadCap Software has released the latest version of its authoring platform, MadCap Flare 12. As a MadCap user for almost 10 years, I’ve had a chance to see firsthand how Flare has developed over the years, and this is a release that I’m excited about.
You can go read the MadCap marketing literature if you want a full rundown of every feature and enhancement in Flare 12. In this article, I’ll share my experience using a preview version of Flare 12 for a month or so before it was released to the public. To honor the 12th major release of Flare, I’ll share twelve features and enhancements I’m excited about.
1. New Advanced Stylesheet Editor
Hands down, my favorite new feature in Flare 12 is the Advanced Stylesheet editor. As you can see in Figure 1, the new editor shows you multiple media types as columns, and you can view as many (or as few) columns as you want at a time. As you scroll through the settings, all columns stay in sync, so you can easily see how a setting is different in various media sections.
Other editor enhancements include the ability to see media query sections in the stylesheet. This allows you to have different CSS settings depending on the user’s display width, automatically adjusting, for example, between desktop, tablet, and phone settings. In older versions of Flare, I would manually add a media query, and then manually adjust the settings in an external text editor. Now the Flare interface will let you create media queries and see their settings as a unique media.
In the bottom left corner of Figure 1 you can also see two new features. The top one allows you to make comments related to a specific style, so you can document as you go, explaining why you have multiple classes of the P element, for example, and how you expect these to be used.
The bottom box shows you information about the property setting you have selected, giving you a definition, and some of the options available for that property.
The new advanced style sheet editor is a huge leap forward. In every Flare training class I’ve given, I warn students that they would inevitably make the mistake of editing the wrong media section, and would be frustrated because the intended change wasn’t implemented. With this new side-by-side display of media types, Flare users won’t encounter this trouble anymore.
2. Multiple Stylesheets to a Topic
This may seem like a simple feature, but it solves a real problem that I continue to see people encounter. In older versions of Flare, you could either choose the stylesheet at the project level, or at the individual topic level. If you only have one stylesheet, this isn’t a big deal, but if you are working with multiple stylesheets (either because you are importing a stylesheet from a parent project, or because you have an advanced use case for using multiple stylesheets), it becomes difficult. If you set it at the topic level, then you’d have to link a stylesheet to all new topics and all new snippets. If you set it at the project level, you couldn’t override it for a single topic.
Flare 12 allows you to select multiple stylesheets for the project and for individual topics. If you are importing styles from a parent project and you want to override a specific style, you can now create a stylesheet that is local to this project, and call it after you call the imported stylesheet, giving you total control over how style settings cascade to show what you want.
3. Cross Reference Enhancements
This is really more of a bug fix than a new feature, but it is a big enhancement in my opinion. In Flare, a cross reference is similar to a link, in that it allows you to point to a different topic in your project. A cross reference differs from a link in some important ways. First a Flare cross reference always shows the heading (or text) of the paragraph that it is linked to, so even if you update the title of the target file, it is updated in all cross references to that title. Second, a cross reference understands where the target topic is contextually, and in printed output will generate text to direct the reader to the correct page.
In older versions of Flare, the cross reference functionality was limited by a bug that wouldn’t show variables in the cross reference text. For example, let’s say I want to create a cross reference to a topic with the first H1 (title) of “<My_Product>’s New Features.” The term <My_Product> is a variable that can be changed globally in the variable editor, or it can be set for individual targets. The problem is that in Flare V11 and older, a cross reference to this topic would look something like this: “For more information, see ‘s New Features on page 20,” completely omitting the variable.
Flare 12 fixes this so that cross references targets can include variables, which is a big win for those who use cross references and variables extensively.
An enhancement to cross references in Flare 12 allows you to insert a cross reference to non-heading content without needing to first place a bookmark in the target location. For example, if you want to create a cross reference to a location in a different topic that uses a drop-down head, you don’t need to create a bookmark in the target. You can just insert a cross reference, and when you select the topic, you can click the bookmark icon. The Select Bookmark window, shown in Figure 3, allows you to point to a variety of content items in the target topic, including paragraphs, headings, styles, drop-down text, table cells, and more.
4. Conditions for Styles
Flare 12 includes the ability to link a condition setting to a style, which may seem curious at first glance, but is surprisingly powerful.
Something I always encourage my Flare clients to do is to create a condition called “DoNotDistribute” which allows you to mark content so it will never get built into an output. This allows you to put author notes and other content inline in your content without worrying that it will get published accidentally. With Flare 12, you can actually create a style for that content and apply the condition to the style. Now when you use the style that has the “DoNotDistribute” condition, that content is automatically conditionalized as well.
Clients often have certain content that is only displayed to their internal audiences and isn’t displayed to the customer. Sometimes this content includes metadata like the version where new content was introduced, or a bug or ticket number that prompted a specific change. These clients are already applying a specific style (so the internal audiences notice this content), and in the past, they also had to do the additional step of marking that content with a condition. With Flare 12, you can just set the condition in the style settings, and now that extra step is eliminated, which reduces the overall chance of forgetting to conditionalize the special content.
5. Snippet Enhancements
Snippets are one of my favorite features in Flare, and in Flare 12, they get a significant boost in functionality. One project I’m working on has over one hundred snippet files. Managing them can be a bit of a challenge. Flare 12 has improved the snippet insertion box so you can pin your favorite snippets for easy access. It also displays a list of recent snippets.
If you’ve ever used snippet conditions (the ability to use the same snippet in two topics with different content, depending on the condition applied to the topic), you’ll love how Flare has enhanced snippet conditions in Flare 12. Now you can either define the snippet condition at the topic level, or you can define the snippet condition at the location it is inserted in your content. This means you could have one snippet used multiple times in the same topic, with different content each time the snippet is inserted.
For example, suppose you have a snippet that contains installation information for both Windows and Linux systems. You can conditionalize the content in the snippet, then you can insert the snippet into two separate locations in a topic. You set the conditions for the first snippet instance to show the Windows content, and you set the content for the second snippet instance to show the Linux content.
In addition, if your snippet includes a variable, you can specify a different variable setting for each snippet instance in a single topic.
I’ve seen people asking for these types of snippet enhancements in the Flare forums, and I’m glad to say that they are powerfully implemented in Flare 12.
6. Conditions in Glossary
If you’ve ever used multiple glossaries so you could provide different glossary terms for different targets, you’ll be interested to know that in Flare 12, you can set a condition for each glossary item, in the same way you can use conditions in other places in Flare.
This gives you powerful control over how glossary terms will appear in different targets, making it so you may only need a single glossary. Generally, I expect this feature to make it easier to maintain glossary terms in Flare.
7. Responsive Output
MadCap is touting this feature a lot in their marketing, and it is pretty cool and powerful, giving you incredible control over how your content is displayed to your customers. It exposes features related to the Foundation grid system, allowing you to create table-like layouts using DIVS, but with the important feature that these items will adjust properly to narrow screen sizes like phones and tablets.
I predict that this feature is something that will not be widely used by average Flare users, at least in the beginning, but I think it lays the foundation for dynamic content unlike anything you’re accustomed to seeing in a help system output. I’m looking forward to seeing how some expert Flare users utilize this ability.
8. Media Queries
While I mentioned this a bit earlier when discussing stylesheets, it is worth mentioning again the ability to work with media queries directly in Flare. For several years, I’ve been doing all my media query entries in the text editor, which can be daunting for some Flare users. By exposing the media queries in the stylesheet editor, as well as in the topics themselves, you can better see how Flare will render your content on a variety of screen sizes.
When authoring in Flare, you can click the “Medium” button on the toolbar, and all your media sections are displayed, including any media queries in your stylesheet.
9. 64-Bit Support
Beginning with Flare 12, Flare is a 64-bit application. That means you will now require Windows 64-bit to run Flare. Most new Windows computers (some statistics say as high as 90%) come with a 64-bit operating system, so if you have a newer computer, you likely already have the correct operating system. (You can right-click on your Start icon and select “System,” and then look at the System Type value, and that will tell you if you have a 32- or 64-bit operating system.
MadCap says the new 64-bit architecture will benefit users with large projects, or users who like to have multiple topics open at the same time, suggesting we will see speed improvements. In practice, I don’t have a way to officially benchmark the speed, but I tested a build of a 550-page PDF target in both Flare 11 and Flare 12. The build time actually increased by about five seconds in version 12, but that’s not very significant for the size of PDF file I was building (2:19 in Flare 11 versus 2:24 in Flare 12).
10. GIT SSH Support
If you’d like to use Flare to connect to source control, but haven’t been able to use the GIT integration because Flare didn’t support SSH connections for GIT, you will be happy to hear that Flare 12 supports SSH for GIT repositories. In today’s world I’m happy to support any technology that increases the security of information that is transferred over a network, so this is a good step forward for GIT users.
11. HTML5 Skin Improvements
If you aren’t using TopNav output, but are using the tri-panel HTML5 target, you should know that with Flare 12, you can now programmatically call different skins via URL. This allows you to have a minimalist skin for context-sensitive help, while retaining a full-feature skin for your traditional help channel. MadCap calls this feature “Runtime Skins.”
12. Track Changes Improvements
When generating to a PDF or Word target, you now have the ability to show tracked changes to a topic. Much like in Word, where you see bubbles to the right of the screen, Flare will generate a Word document, or a PDF document with these change bubbles. This allows you to easily show what changes you’re proposing to a topic in a format that is easy to share with your colleagues. These changes are automatically generated into the Word document, so you can enable “Show Changes” in Word to see them after the Word document is published.
Summary
Flare 12 is a great improvement for my favorite authoring tool. It has a nice mixture of changes that enhance the writing experience for the help authors, as well as changes that affect our customers who use the documents we create. There are a ton of other features, big and small, that I wasn’t able to cover in this review including enhancements around multilingual output, help output that is live or local, high DPI support, page breaks, and more. You can find out more about the latest version of Flare at www.madcapsoftware.com, where you can also request a free trial of Flare.
PAUL PEHRSON is a seasoned technical writer, MadCap Flare trainer and consultant, and the father of five children. He has served in leadership positi ons in his local STC chapter, as well as serving on various STC committees. He lives in a suburb of Salt Lake City, Utah.
