Take Giant Steps to MadCap Flare Mastery

by Eddie on September 26, 2010 · 4 comments

in Books, Learning Resources, Reviews, Software, Technical Communication

Looking to learn MadCap Flare? If you’re a new Flare user, you’re probably feeling a bit intimidated. Features abound, and the learning curve is steep.

You can embark on several learning paths to Flare mastery:

  • Try Flare’s excellent, comprehensive online help. The problem is, you may not understand certain concepts well enough to know where to start.
  • Take a MadCap course. They offer a Basic-to-Intermediate class for beginners. They also offer Advanced CSS and Single Sourcing classes.
  • Try the excellent topical guides (PDF) under Flare’s Help > Guides submenu. The guides provide a structured, linear learning approach.

All three options are great learning paths, but what if you want a comprehensive reference book?

Easy. Buy Five Steps to MadCap Flare by Lorraine Kupka and Joy Underhill. The authors are Technical Communication pros with over 40 years of combined experience between them. If you’re new to Flare, you can adopt their best practices from the start. If you’re an experienced Flare user, you’ll get a broad perspective that you can apply to existing projects.

Learning by Example

For readers who are new to topic-based authoring, Five Steps gives an excellent primer in the short chapter called Document Basics. The organization of this chapter—and all chapters, for that matter—exemplifies the practice of modular writing. The authors organize Information in easily digestible chunks with clear labeling. They also provide short reference sections such as Terms to Understand and include brief, easily scannable tables to help you sort out various options.

A Quick Tour provides a brief orientation to the Flare interface, emphasizing the conventions used in many of the side panes and settings windows. The chapter includes plenty of annotated screen captures to help orient you to the UI components.

Breaking your Stride

Don’t make assumptions about the notion of learning Flare in five steps. Kupka and Underhill have crafted each “step” as a category that subsumes a large chunk of knowledge. I’ll summarize the steps here and add some of my own comments.

Step 1: Get Started

This step gives pointers for planning your first Flare project, teaches you how to the perform common tasks, and introduces you to Flare templates.

Many Flare users plunge into creating a project without pre-determining the nature of its content and purpose. Planning your Flare project gives you guidelines in the form of questions. For example, do you already have source content or do you need to create it? Will you deliver both online and printed versions? How will your content be reviewed? The authors provide a useful roadmap in table form to help you make the right decisions.

If you’re used to creating templates in applications such as Word or FrameMaker, you’ll find Flare’s template model to be far more versatile and expansive. A Flare project can serve as a template, and each of its internal files can be templates, too. You can save most files outside of a project and reuse them in multiple projects. Since most of them are XML files, you can view them in a text editor. Flare 6 introduced the Template Manager, which makes saving and reusing templates much easier. In the section titled Working with Templates, the authors recommend best practices for using templates and explain how to use the Template Manager.

Step 2: Learn the XML Editor

Although the Flare authoring environment works like a word processor, it’s packed with features that are unique to the application. Step 2 walks you through nine core tasks for learning and customizing your environment. De-cluttering your workspace suggests that you close the panes on the right to increase your viewing space. (I also recommend saving customized workspaces for various tasks.) The Learn More section covers key visual indicators such as the structure, tag, and span bars.

Step 3: Develop Content

In this step you learn how to work with essential content elements. Here’s a partial list of covered topics:

  • Working with lists provides thorough coverage of single- and multi-level lists, including how to rearrange, sort, re-number, and merge them.
  • Working with tables explains basic tasks such as inserting, deleting, and moving rows and columns. Since Flare also uses specialized style sheets for tables, the authors continue the subject of tables in the formatting section. I second their recommendation that you create and store table formats in templates for reuse.
  • Working with images explains how Flare manages changes to images. This section thoroughly covers resizing images and explains how resizing affects their quality.
  • Formatting your content and Customizing styles both provide advice for controlling the appearance of your online and print content. You can supplement this information with one of my recommended books on CSS.

Step 4: Create Navigation Aids

The Help authoring community has many lively online discussions about navigational elements included in application help. For example, whether to include or exclude an index always seems to rouse passion.

In Step 4, the authors avoid editorializing about what to include or not include in your projects. They simply explain how to add and manage all of the available aids that Flare offers:

  • Creating a Table of Contents provides thorough coverage of how to add one or multiple TOCs and how TOCs support online and print output.
  • Creating links provides a useful table that describes all of the types of links that you can add to a Flare project. It explains how to add each type, including the Related Topics help control.
    Tip: If you’re using Flare 6, don’t forget about the Link Viewer, which enables you to trace link paths and dependencies.
  • Adding cross-references explains how to add cross-references for your print output. Flare has great power and versatility for creating and managing cross-references. For example, contextual page number references can detect whether a referenced item is above or below the discussion point.
  • Creating index entries explains how to add index keywords to your projects by adding markers to topics. (Like Word and FrameMaker, Flare uses embedded markers.) This section also covers how you can vary index output by adding conditional tags to markers.
    Another Tip: I’m a big fan of the Index Explorer (View > Index Explorer), and it’s greatly improved in Flare 6. Use this feature to monitor the state of your index during project development.

Step 5

Step 5 is split into two sub-steps, with 5A covering printed output and 5B covering online output. In both sections, you learn to set up project components and build the output.

Step 5A: Create Print Output
The good news about creating print output from Flare is that once you set it up, you can easily update and regenerate the content. The bad news is that setting up printed output is arduous. In fact, I’ve written a six-part series covering Flare print publishing.

Fortunately, Five Steps gives you a logical, well-planned strategy that includes preparation and decision-making. The authors divide the process into nine tasks. They recommend that you start with a simple print document so that you understand how to build the components, then graduate to a more complex document with multiple sections.

I’m a fan of this approach. I typically create (1) a simple print setup for sending individual or groups of topics to reviewers; and (2) a more complex print setup for double-sided, multi-sectioned documents.

Step 5B: Create Online Output
This sub-step follows a similar progression to Step 5A. The main difference is that it focuses on online components such as master pages and skins. It also includes a useful Testing and troubleshooting section.

Supplementing Your Learning

The five-step process summarized in this review gives you the core skills you need to master MadCap Flare. But the authors didn’t stop there. Appendices A through H offer useful, detailed supplementary information, including the following:

  • Appendix A: Planning Worksheets includes the following worksheet examples for Flare projects:
    • Defining content sources
    • Defining project outputs (Example: WebHelp, WebHelp Mobile)
    • Determining how reviews will be handled (Example: MadCap X-Edit, MS Word)
    • Establishing project settings (Example: location, source control bindings)
    • Recording your target settings (Example: master page, medium, condition tags)

    These worksheets help you with planning and tracking. They also provide a concrete trail for another author who might serve as your backup or who might eventually inherit your project.

  • Appendix B: Import Content explains how you can import MS Word, FrameMaker, or HTML files into Flare.
  • Appendix C: XML Reference summarizes the XML Editor UI elements, including toolbars, cursors, and shortcuts.
  • Appendix D: Context-Sensitive Help eloquently breaks down the process of mapping topics to UI elements.
  • Appendix E: Troubleshoot offers tips such as fixing broken links and interpreting build errors.
  • Appendix F: Single-Sourcing focuses on Flare features used in single-sourcing content, including condition tags, snippets, and variables.
  • Appendix G: DITA Import and Export explains how to get DITA content into Flare and how to export it from Flare.
  • Appendix H: The Next Step provides a roadmap for exploring additional Flare features that are not covered in the book.

Summary

In Five Steps to MadCap Flare, Lorraine Kupka and Joy Underhill have provided a clear, easy-to-follow guide to mastering Flare. They start with tool-agnostic, sound advice on planning an information development project. In the Flare development context, they emphasize projects and templates as the key building blocks.

I also appreciate how the authors set best practice examples for all information developers to follow. They write in plain, conversational language. They use consistent conventions that facilitate ease in finding information. And they’re damn good teachers.

Buy the book now.


Back to top

{ 4 comments… read them below or add one }

1 Ivan September 28, 2010 at 1:28 am

Hi Eddie,

Thanks for the Link Viewer tip – hadn’t thought of that.

Using lists and headings like you said really works for me, too.

Ivan

Reply

2 Craig October 1, 2010 at 9:33 am

When I click “Buy the book now,” the link appears broken. The server can’t be found.

Reply

3 Eddie October 1, 2010 at 2:07 pm

Thanks for letting me know, Craig. The site may have been temporarily down for some reason. I’ve tested the link both before and after writing the post, and it has always worked for me.

I’ll let the authors know.

Reply

4 Joy Underhill October 3, 2010 at 4:31 pm

Hi Craig.
I just checked the ordering button and it seems to work fine. Please contact me directly at joy@northcoastwriters.com if the problem continues.

Reply

Leave a Comment

Previous post:

Next post: