A MadCap Flare project can easily house the documentation needs of an entire team, as a single project is made up of a range of different files and can create multiple types of outputs. But let’s take a moment to talk about the files. Over time, users will understand all the various file types that are included in a Flare project. However, for a new user, there are three core files that are essential to understanding topic-based authoring in Flare and coincidentally, they all start with the letter “T”: Topics, TOCs, and Targets.

Topics

What exactly is a topic? A topic (from Wikipedia):

  • Is a discrete piece of content about a specific subject
  • Has an identifiable purpose
  • Can stand alone

Topic-based authoring provides a modular approach to creating documentation in comparison to a document-based approach like in Microsoft Word. In Flare, we start off by creating small topics then later string them together or assemble them for our output.

In Flare, topics live in the Content Explorer. When it comes to topics, think of the Content Explorer as a storage location that all Flare topics will live in. Topics can be organized in any fashion regardless of how they will appear in the documentation.

20170713 topics tocs targets 01

Topics are authored within the XML editor and can include your text, images, multimedia and links. Create some topics and start adding content!

TOCs

TOC, short for “Table of Contents”, are always used in Flare projects. But when it comes to effectively configuring a Flare project, it’s helpful to understand the importance of structuring a TOC.

Here’s a common process that many new users follow:

  1. Create a Flare project
  2. Add New Topics to Flare project
  3. Build a Target
  4. View output

The result? A lot of head scratching and wondering “Why can’t I see any of the topics I’ve created?” A way to save time and effort later on is to adapt the third step above: “Add topics to a TOC”. Now, the TOC serves as your blueprint for how topics will be structured in your document. As a Flare author you have the means to architect the order and hierarchy of Flare topics, which is easily done with the TOC.

Your TOCs are stored in your Project Organizer. To start adding topics to a TOC, open up a TOC file (or add one if you don’t have one already) and begin clicking and dragging topics from the Content Explorer into the TOC.

20170713 topics tocs targets 02

Targets

Every deliverable created from Flare will be created from a Target. I like to refer to Targets as a “Recipe” file, as it is the file that allows a user to pick and choose exactly which TOC, Conditions, and Variables will be used in an output.

In order to select which TOC is to be used in a Target:

  1. Open a Target file
  2. Under the General tab select the “Master TOC” dropdown
  3. Select a TOC file
20170713 topics tocs targets 03

Once this is set up, hit the “Build” button and Flare will start its engine then...done! You’ve successfully created topics, added them to a TOC, and built an output. Now, hit the “View” button and you can see what you’ve created from Flare.

Note: The TOC for an online output is essentially used to structure how a user will navigate through the help. However, by default for online outputs, topics that aren’t explicitly set to be excluded from a target will be included in the output. You can see an example of this in online help if you search in for a topic that is not included in your TOC. If you would like to exclude topics that are NOT included in the TOC, select the “Exclude content not linked directly or indirectly from the target” option in the Advanced Tab of the Target editor. Check out Flare’s help for more information.

Summary

To summarize, here’s the three file types that are important for every Flare user to know:

  • Topics = Content or building blocks of documentation.
  • TOCs = A file to layout, structure, and string your topics together.
  • Targets = Your output configuration file.

At a high level, here’s some steps to understand how to work with content in Flare.

  1. Create a Flare project
  2. Add New Topics to Flare project
  3. Add topics to TOC file
  4. Build a Target using the TOC that was created
  5. View output

In my experience with Flare, I’ve heard some analogies thrown around in the best way to describe the relationship between the three T’s. Here’s some of my favorites.

Using Legos as an example:

  • Topics = LEGOs
  • TOCs = Canvas that you place the Legos on
  • Targets = The entire LEGO model

Or a cooking analogy:

  • Topics = Individual ingredients
  • TOCs = The pot you’re putting the ingredients in
  • Targets = Recipe this is what we are cooking

Can you think of any great analogies for the three T’s that could help new users? Comment below and let us know!