Article Summary:

Are you currently using Adobe® FrameMaker® and considering moving to MadCap Flare™? Are you using a different tool such as Microsoft Word and considering moving to FrameMaker® or Flare? This article can help.

FrameMaker® certainly has a long history as a leading publishing tool for complex technical documentation. In fact, FrameMaker® turned 25 in 2011. It is still a great tool, and Version 10 includes a number of UI and feature enhancements.

Even with its rich feature set and several face lifts, however, FrameMaker® is past its prime for the following reasons:

1. In this day and age of nimble, modular content, FrameMaker®’s primary output is still print.
2. Using FrameMaker® to publish content to the web requires additional tools and plug-ins.
3. FrameMaker®'s user interface still looks and feels dated. Although the toolbars look more streamlined, many dialogs retain the Windows 3.1 look. Cryptic, non-intuitive conventions persist.

MadCap Flare is a great alternative to FrameMaker®. Flare not only gives you the publishing power of FrameMaker®’s best features; Flare's modern, modular interface enables you to single-source your print and online content without needing additional tools. You can certainly enhance and extend your user assistance solutions with other great tools in the MadPak suite, but Flare alone provides a complete, comprehensive publishing solution.

Note: This article compares various capabilities of FrameMaker® and Flare as single-source publishing tools. I assume no prior knowledge of either tool. Even if you know one or both tools reasonably well, I hope that the article will still give you some perspective on the differences between them. Since I occasionally mention Flare features that are outside of the intended scope, I have provided a list of related links at the end.

Product Architecture

Let's start by taking a look "under the hood" of FrameMaker® and Flare.

FrameMaker® File Types

Native FrameMaker® files have the extension .fm. They are binary files and are used to create unstructured documents. You can also create a book file (.book), which serves as a container for individual, sequential documents (chapters).

Using the Save As command, you can save native FrameMaker® files in the following formats: MIF, RTF, PDF, TXT, XML, and HTML. To output any type of compiled HTML help, you need a separate tool such as Flare, RoboHelp, ePublisher, or mif2go.

FrameMaker® can also publish structured documents that validate to a Document Type Definition (DTD), including DITA and S1000D.

Flare File Types

Flare’s base production unit is a project. When you create a new project, Flare creates a folder that serves as a container for the Flare project file (.flprj) and various subfolders. The project folder and project file share the same name. If Flare is not currently running, you can open both the application and the project by double-clicking the project file in Windows Explorer.

The contents of the various folders play specific roles in building, presenting, and maintaining your project (Figure 1). This structure enables you to easily move your entire project and keep all file relationships intact.

Figure 1. Flare Project folder contents

Flare configuration files are pure XML. Opening them in a text editor reveals the underlying elements and attributes that correspond to settings and properties used in the GUI. The open architecture of XML and XHTML enables authors to easily share both topics and configuration files among projects and through Windows Explorer.

The native file type for Flare content is W3C-compliant XHTML. Instead of creating other file types using the Save As command, you set up configuration files called targets for publishing various outputs. Target files (.fltar) enable you to set up publishing variations using conditions, runtime variables, and other specifications. Using targets, you can publish to the following formats: PDF, DOC/DOCX, XPS, FM, XHTML BOOK, and DITA. You can also publish the following types of compiled help: Adobe Air Help, DotNet Help, Microsoft HTML Help (.chm), WebHelp, WebHelp Mobile, and WebHelp Plus.

Authoring Environment

When considering tools, technical writers often rate the authoring environment as number one in importance. Efficient, usable authoring features enable us to get our work done and meet our deadlines.

FrameMaker® Authoring

The FrameMaker® authoring environment is similar to that of most word processing tools. Writing follows a linear, page-based flow. You can create individual chapters (.fm files), wrap them in a book file (.book), and number sections, chapters, and pages across the files in the book. Text formatting is handled through Paragraph, Character, and Table catalogs.

Unless you reconfigure the environment, files are listed on the left, open files show in a tabbed configuration in the center, and style catalogs and other features appear in the fly-out pods on the right (Figure 2).

Figure 2. FrameMaker® authoring environment

Flare Authoring

Flare was built from the ground up to support topic-based writing and multiple-output publishing. The native format for Flare topics is XHTML, with CSS used for presentation. You can manage style sheets through a built-in GUI or through a text editor. MadCap has included optional extensions that provide sophisticated enhancements, including custom style attributes and flexible cross-referencing formats for print.

Whereas in a FrameMaker® authoring workflow you would typically combine topics in a single chapter, Flare authors commonly create and maintain topics as separate files. This practice promotes more modular content, which is useful when you need to serve multiple, varied combinations of content to subsets of your customers.

Figure 3 shows the Flare authoring environment with a view of two commonly used features:

• The Content Explorer on the left (numbered 1 in the image) enables you to view your project content in a tree view.
• The XML editor in the main part of the window (numbered 2 in the image) is where you create and edit content.
  • Note the structure bars along the left side of the editor (2). These bars show the underlying nodes of the XHTML tree, starting with the body tag. Besides offering a visual perspective, they enable you to precisely select specific content.
  • A Preview button on the XML Editor toolbar (just above the number 2 in the image) offers a drop-down list of preview formats. You can preview a topic as it will appear in any of your target outputs (such as HTML, PDF, or MS Word). Although the preview may compile for a few seconds, previewing a topic while authoring is much more convenient than repeatedly compiling the entire project.

Figure 3. Flare authoring environment

Conditions

Conditions enable you to publish multiple versions of your content from one set of source files. For example, say that you are writing a user's guide and an administrator's guide for the same product. Both guides include some identical content but also have extensive variations. You can create conditional tags called User and Administrator and apply them to mark content that is specific to each group.

Let's say that publishing requirements are different for the two groups. You need to publish two versions of the guide: a printable guide (PDF) for users only, and searchable online help (HTML) for both the users and administrators (with variant content). You might then need two more conditional tags: PrintOnly and HelpOnly.

FrameMaker® and Flare both support conditions. The following sections explain how they are implemented in each application.

FrameMaker® Conditions

FrameMaker® enables you to add, edit, show, and hide conditions for various scenarios. You can also build Boolean expressions to include, exclude, or combine tags.

Figure 4 shows the main dialog boxes used for working with conditions:

• Add/Edit Condition Tag (1): Used for creating or editing a condition tag, applying a style, color, and background color. This dialog also tracks all instances of the active tag in the current document.
• Show/Hide Conditional Text (2): Controls which conditions are included in an updated book. You can show content by condition or using a custom Boolean expression. This dialog also has a Build Expression button that opens a second dialog for building and editing expressions.

Figure 4. FrameMaker® dialogs for working with conditions

You can apply conditions to text in a document using the Conditional Text pod (Figure 5).

Figure 5. FrameMaker® Conditional Text pod

Flare Conditions

Flare conditions are similar in function to FrameMaker® conditions, but the process of creating, maintaining, and reusing them is a lot more flexible. You create Flare conditions as condition tag sets, which are stored in the Project Explorer as separate files with the extension .flcts. You can cut, copy, and paste conditions between sets. You can also store condition tag set files outside of your Flare projects, use them in multiple projects, and share them with other authors.

Figure 6 shows an example of Flare conditions. The drop-down control on each color band opens a dialog box where you can pick an alternative color or sample a color from your computer.

Figure 6. Flare condition tag set

To apply a condition to text in a topic, you select the Format, Conditions menu command. You then check a box in the Condition Tags dialog box (Figure 7).

Figure 7. Flare Condition Tags dialog box

As in FrameMaker, you can show or hide conditional text as you write. Figure 8 shows a very short topic that serves as either an introduction for a book chapter or a landing page for a section of a WebHelp project. Text marked with the OnlineOnly tag is red, and text marked with the PrintOnly tag is green. The plain-looking paragraph at the bottom is actually a container for a referenced snippet file, which is discussed in the Modular Content section.

In the left side of Figure 8, note the colored squares preceding certain folder and file names. The colors indicate that conditions have been applied to entire folders and files. The files in the book_structure folder are special print-only topics that are used only for building a printed book. Thus, the entire folder is tagged as PrintOnly.

Figure 8. Flare conditions applied to text, folders, and files

When you combine various condition tags with the power of Flare targets, you can establish endless variations to your project output. Figure 9 shows the Conditional Text tab in a target file (.fltar) with settings for PDF output.

Figure 9. Flare PDF target with condition settings

Variables

Variables store text strings that appear repeatedly in your content. Instead of retyping that same text over and over, you simply define and insert a variable wherever the text should appear.

For example, you might create a variable to store the name of a software application that is the subject of a user's guide. If your clients decide to change the name of the application in mid-project, you can simply change the variable, update your guide, and every instance of the name is changed.

FrameMaker® and Flare both support variables. They both have built-in system variables for dates, times, section numbers, and other attributes. They also enable you to create custom variables. In both applications, stored variables are pure text strings, devoid of formatting. You can apply formatting such as bold or italics after inserting a variable in a document or topic.

FrameMaker® Variables

FrameMaker® stores variable definitions in documents, and you can import variables from one document to another. You manage variables through a combination of the Variables pod and a dialog box, as shown in Figure 10.

Figure 10. FrameMaker® variables

FrameMaker® variables do not have any identifying visual attributes in running text, but clicking anywhere in a variable string highlights the entire string. You can also search for variables, either globally or by name. You can then use the Variables pod to edit a variable definition or convert a variable to text.

Flare Variables

Flare variables are stored in sets. Variable sets are XML files with the extension .flvar. When you open a variable set in Flare, the variables are displayed in a table. You can simply double-click a variable definition to edit it.

In the following examples, the first set of variables is specific to a software application and a guide. The second set provides information about the organization developing the software, including contact information for support.

Figure 11. Flare variable sets

When viewed in the Flare XML Editor, variables are surrounded by square brackets. Right-clicking between the brackets opens a shortcut menu with commands that allow you to select, copy, delete, or open the relevant variable set for editing. You can also turn on visual settings that precede a variable with its name and highlight the variable string. Figure 6 shows two instances of a variable called AppName. In published content, the same variable instances appear as running text (formatted or non-formatted).

Figure 12. Visual indicators for Flare variables

Figure 13. Flare WebHelp target with variable settings

Modular Content

Variables are great for storing and reusing strings of text, but what if you need to reuse longer blocks of content? For example, what if you need to reuse an entire topic in certain deliverables but not in others? What if, when printed, the content spans several pages?

You need modular content, where you assemble chunks of content in various configurations. In the world of content management systems, this is known as component content management. You can modularize content in both FrameMaker® and Flare, too.

Modular FrameMaker® Content: Text Insets

FrameMaker® can handle modular content in various ways, but the most common method is through the use of text insets. Text insets are external files that you import into a FrameMaker® document by reference. Text insets can range from a paragraph to a chapter and can include formatted text, tables, images, variables, and conditions.

In Figure 14, the section labeled Conventions Used is coming from a separate file. Since the conventions table is used in numerous deliverables, it is updated in and referenced from one file.

Figure 14. FrameMaker® text inset: Text Conventions Used

When you import text insets, you can specify whether to use formatting, variables, and conditions from the source document or the container (receiving) document. You may need to do some testing to get the result you want.

When managing content that includes text insets, you have to be very careful when you move files. For example, if your team stores text insets in a central folder and you move your book to a new location, you may need to redirect the referenced files. This can become quite tedious if you have a lot of linked references.

Modular Flare Content: Snippets

Flare snippets are chunks of content that you can reuse in one or more Flare projects. Where variables are unformatted strings, snippets can be anything from a paragraph to a full topic. They can include formatted text, tables, images, variables, and conditions. You can apply conditions to specific content in snippet files, or you can conditionalize the entire file.

Snippet files (.flsnp) are stored in the Resources folder of the Flare Content Explorer. Figure 15 shows a snippet file for reusable content that no one wants to recreate: Copyright and License Information.

Figure 15. Flare snippet: Copyright and License Information

Figure 16 shows a snippet file that contains nothing more than a div with a paragraph and a content placeholder called a mini-TOC proxy. (A Flare proxy is simply a placeholder for content that gets generated during runtime.) The entire div has been conditionalized for print output. This snippet is referenced at the beginning of every chapter of a printed book. The lower half of the figure shows how the snippet appears in a book, with the output format coming from CSS. Notice that the mini-TOC proxy has been replaced with an aggregated list of topics in the chapter.

Figure 16. Flare snippet: mini-toc proxy for print

Flare's snippet conditions are also a useful feature. You can conditionalize text within snippets to show variations in your content according to audience and context. These conditions can then be used to override target conditions. This is an effective method for one-off variations or exception cases.

Snippet files that are stored in a Flare project travel with the project. If you move the project folder, the snippets go with it. For purposes of standardization, your team can maintain a global project and link to snippets (and other file types) from individual projects. You can also share snippets through SharePoint, a source control system, or via Flare's External Resources feature, which enables you to establish synchronization with externally stored files. To learn more, see the list of related links at the end of this article.

Style Management

If you are reading this article, I assume that you are familiar with styles, the formatting collections that are widely used in word processing, desktop publishing, and web content production. FrameMaker® and Flare have powerful features for supporting styles, though their approaches are very different. Let's take a look.

FrameMaker® Tags and Formats

Styles in FrameMaker® are formally called tags. You can apply FrameMaker® tags using the fly-out Paragraph, Character, and Table catalogs that are docked to the right side of the authoring environment. Each catalog has a corresponding Designer that you can use to change tag attributes.

Catalogs and Designers

Figure 17 shows the Paragraph Catalog and the Paragraph Designer. Note the six buttons at the top of the Designer. They represent six sets of attributes: Basic Settings (Indents, Alignment), Default Font, Pagination, Numbering, Advanced Settings (Hyphenation, Spacing), Asian Character Settings, and Table Cell Formatting. The Commands drop-down in the lower left enables you to clone a tag, globally update tags, delete tags, and set attributes to match a selection.

Figure 17. Paragraph Catalog and Paragraph Designer

FrameMaker® Table Support

The FrameMaker® Table Designer has a similar structure to that of the Paragraph Designer. Three buttons at the top offer various options for setting up table structure and design: (1) indents, spacing, margins, and alignment; (2) appearance of rules for the entire table, including headers and footers; and (3) shading patterns for alternating rows or groups of rows. Figure 18 shows the initial Designer window.

Figure 18. FrameMaker® Table Designer

FrameMaker® Numbering and Cross-Referencing Support

FrameMaker's Building Blocks approach for section, chapter, and paragraph numbering is robust. In addition to creating complex, multi-level numbering schemes, you can implement auto-generated labels such as Note and Warning. If you have ever wrestled with Microsoft Word's cryptic, faulty numbering, you will appreciate FrameMaker's Building Blocks for numbering.

Figure 19 shows the Numbering setup in the Paragraph Designer. Note that simple list numbering is set up with a number series (N), followed by in increment variable, a plus sign, a period, and a tab character: N:<n+>.\t

Figure 19. FrameMaker® numbering setup

FrameMaker® also excels at custom cross-reference formats. You can establish a range of formats, from "see page 5" to "See Chapter 5, About Widgets, on page 5." The Cross-Reference dialog enables you to select a paragraph tag and use it to build the cross-reference string. A format for my second example would look something like this:

See Chapter <$chapnum>, <$paratext[Chapter Name]>, on page <$pagenum>.

Flare Style Sheets

Flare formatting comes from Cascading Style Sheets (CSS), with support for both the CSS1 and CSS2 specifications. You can use Flare's built-in style sheet, or you can import your own. Flare includes an optional setting to enforce the use of only one style sheet, but you can use as many style sheets as you need.

Style Sheet Media

The built-in style sheets offer three media: default, non-print, and print. I have never used nor needed the non-print medium. I typically set up most styles under the default medium. I use the print medium for (1) styles that appear in both online and printed content but have different attributes; and (2) styles that appear only in print.

Figure 20 shows the Flare Stylesheet Editor. The second of the three drop-downs at the top shows that the default medium is active. The <body> tag is selected on the left. Since this is the setting that I use for online output, the body tag is set in a sans serif font, with a reference point of 10 pixels. (I use ems to establish relative sizes for other tags.) In the foreground, note that the print medium is active. The Body default is set in serif, with a size reference of 11 points.

Figure 20. Flare Stylesheet Editor with different media displayed

Flare Table Support

Flare project style sheets support formatting for standard table tags such as <th> and <td>. You can use standard tags to establish conventions for most tables and create variations using dedicated table style sheets. These are specialized CSS files with MadCap extensions.

Figure 21 shows an open table style sheet. Note the following features:

• The tabs on the left control general settings, as well as settings for rows, columns, headers, and footers. These settings enable you to apply different row and column patterns for presentation.
• The drop-down at the top enables you to select style sheet media, as in the main project style sheet.
• The Apply Style button opens a window from which you apply table styles to selected folders or files. You can choose to overwrite existing formats and remove any locally applied formatting.

Figure 21. Flare Table Style Editor

Flare Numbering and Cross-Reference Support

Flare's approach to numbering and cross referencing is similar to that of FrameMaker. The main difference is that both features are implemented as MadCap CSS extensions. All extension names are preceded with mc.

Figure 22 shows an example of a format used to number chapters in a printed book. Note that the extension for numbering is called mc-auto-number-format. The chapter numbering format uses the following patterns for numbering Headings 1 and 2:

CH:Chapter {chapnum}

CH:{chapnum}.{n+}

Figure 22. MadCap extension for auto-numbering in print

Cross-reference formats for print output are implemented as children of a MadCap | xref extension. Figure 23 shows a cross-reference string. Note that the formatting tags are HTML in this case.

{color indigo}{i}{paratext}{/i}{/color} on page {page}

Figure 23. MadCap XRef format

Editorial Review

FrameMaker® and Flare both support editorial reviews and change tracking. This section compares how those features are implemented.

FrameMaker® Review Features

Adobe began to introduce review features to FrameMaker® in version 8, and those features have evolved since then. You can now use the Track Text Edits feature to do the following:

• Set the scope of reviewed changes to the open document, the open book, or to a group of documents that you have selected from the chapter list in the left pane
• Preview the document in pre- and post-change states
• Select changes by user
• Accept or reject changes individually or collectively

All of the features are available through both the Track Text Edits toolbar and menu (Figure 24).

Figure 24. FrameMaker® Track Text Edits toolbar and menu

I was encouraged to see that you can now import PDF comments from reviewers. When creating the PDF review file, you need to ensure that the file is tagged for accessibility. (You're already doing that anyway, right?) Once you receive review comments, you can then import them into the corresponding FrameMaker® file.

When you try importing comments for the first time, you may think that the import didn't work. This is because the imported content is stored in markers, which are not visible unless text symbols are turned on. Even if markers are visible, they may not be where you expect. One of my two markers ended up in the chapter title instead of the applicable Overview section. The other ended up in a cross-reference on the first page of the chapter, with the actual content five pages away.

Conclusion: While these features are certainly a welcome addition, they are obviously still evolving.

Flare Review Features

MadCap introduced review features in Flare version 6, along with an integrated text editor called X-Edit. When Flare 7 was released, X-Edit was replaced by the more robust MadCap Contributor. Flare has its own built-in reviewing features, so you don't need Contributor to track changes and add annotations. You do, however, need Contributor to share native Flare files with reviewers and have them provide comments. You also need Contributor if outside authors are writing content.

Yes, this is the one exception where Flare currently requires a separate tool (but then once again, so does FrameMaker). Contributor is inexpensive, but if you have no budget for it, there is a workaround:

1. Create a Word target and set it up to include a bundle of selected topics for reviewers and contributing authors.
2. Add a cover page with the date and a mini-TOC of included topics.
3. Set up a Word import workflow for that maps to your style sheet.
4. When your reviewers send their proposed changes and new content, accept or reject the changes, then import the content.

Figure 25 shows the Flare Review toolbar and menu. The first part of the toolbar and the first four commands on the menu are related to bundling, sending, and receiving review packages to and from MadCap Contributor. The rest of the commands do not rely on Contributor. They enable you to turn Track Changes on and off, navigate through changes, and accept changes individually or collectively.

Figure 25. Flare Review toolbar and menu

If you simply need to add your own annotations and tracked changes, Flare has all of the built-in features that you'll need. Figure 26 shows a Flare topic with annotations.

Figure 26. Annotated Flare topic

Reports

FrameMaker® has no significant reports. For verification, select the following menu command: File, Utilities, Document Reports. You will find two reports: Asian Character Count and Word Count. That's all. To run other reports, you need to buy report generating tools created for FrameMaker® from some of its dedicated software vendors.

In contrast, Flare has always provided a number of reports, and Flare 7 introduced even more. In fact, according to MadCap, you can now combine Flare reporting configurations to produce up to 900 different types of reports. Select Project, Add Report File, and the Add Report dialog opens (Figure 27). Notice that you can select from a number of categories, or you can select Empty Report and decide on the topic after you add the report to your project. Here I have created a report on conditions:

Figure 27. Adding a report

The report file is added to the Reports folder in the Project Explorer, and Flare opens it in the Report Editor. Numerous check boxes enable you to try different combinations until you configure exactly the data that you want to see.

Figure 28. Editing a report

Once you configure the report and click the Generate button, you can view the report in a browser and add it to an archive. Archived reports are stored as HTML files under the ../Projects/Archive folder in Windows Explorer. For historical data comparison, you can also view archived reports in the Archive tab of the Flare Report Editor.

Publishing

Publishing from FrameMaker® can become quite complex when you are managing multiple conditions. The FrameMaker® authoring environment doesn't always lend itself well to such a degree of complexity. Dialog boxes open other dialog boxes, giving you only one piece of the puzzle at a time. The big picture can seem out of reach. Add other tools to the mix, and the complexity increases.

In contrast, Flare provides a dynamic solution for multiple publishing variations in the form of targets. I have given examples of targets in other sections of this article, but I want to re-emphasize their importance as a single-source publishing mechanism. Targets are not just configuration files; they specify all of the elements that differentiate each output channel in one place. They enable you to see the big picture while focusing on the individual building blocks underlying each publishing scenario.

Targets enable you to do the following:

• Set your output medium and supporting files such as style sheets, master pages, and page layouts
• Set conditions to establish who will consume your content and in what media
• Fine-tune variations in your output with runtime variables
• Set up destinations for publishing your projects to servers
• Specify how glossary terms are represented in your output (static or dynamic)
• Use relationship tables to dynamically linke topics, both in DITA and non-DITA publishing output
• Specify parameters for file naming, image handling, performance, language, and other advanced settings
• Set up a feedback service
• Specify settings to maximize the accessibility of your content

Conclusion

I hope this article helped you understand the similarities and differences between FrameMaker® and Flare. I can best summarize by saying that I believe Flare is the more modern, forward-looking tool. I say this as a former user of FrameMaker® and a long-time admirer of the product. I simply think that Frame is past its prime. Regardless, I recommend that you download a trial of both tools and decide for yourself.

I have covered a lot in this article, and yet I have only scratched the surface of Flare's capabilities. For example, I didn't mention that while Flare is not a DITA authoring tool, it can import and publish DITA content. I didn't cover how to set up an infrastructure for publishing print content from Flare, but I have included a link to a series of blog posts that I wrote on that subject.

As a supplement to this article, I encourage you to explore the following Related Links.

Related Links

• Ten Tips for Importing FrameMaker® Content into Flare

  Are you already using FrameMaker® and considering moving to Flare? If you're worried about how to get your FrameMaker® content into Flare, my first MadNewz article can help.

• Advanced Use of Condition Tags and Single Sourcing

  In this MadNewz article, Senior Technical Writer Patti Short provides detailed examples of how you can harness the power of Flare conditions and targets.

• Review of MadCap Flare 7

  I published this comprehensive review of Flare 7 just after the product release in the first quarter of 2011. The review spotlights a number of features that I only mentioned or didn't have time to discuss in this article.

• Flare Print Publishing, Stage 1: Laying the Foundation

  Flare can handle long printed documents as well as FrameMaker® can. Between December 2008 and February 2009, I published a set of six articles covering best practices for setting up a Flare infrastructure for print publishing. The Flare GUI has undergone some changes and improvements since I wrote those posts, but the basics are still the same. I plan to revisit the subject this year.

• Complete Flare WebHelp Online

  MadCap publishes the complete WebHelp for all of its products on the Support page of their site. I encourage you to view and browse through the Flare WebHelp for more information about the topics discussed in this article.

The majority of our content will come from users just like you. If you would like to become a contributing writer for a future MadNewz article, please email madnewz@madcapsoftware.com.