MadCap Flare: managing your project and content

This blog is the last in a series that discusses the intricacies of working in MadCap Flare. In this series, you can find a selection of good practices, gathered and tested by the 3di Authoring Team, and curated by our in-house MadCap Advanced Developers.

If you’d like to learn more about the basics, or about creating documentation portals in MadCap Flare, head to our former posts:

• MadCap Flare tips and tricks
• MadCap Flare: editing your documentation’s portal front-end

This post walks you through our best practices in managing your Flare project and content, which include:

Editing the table of contents in MadCap Flare

The table of contents (TOC) in Flare can be a complex structure, and knowing a few tricks around them will save you valuable authoring time. This section covers the following actions:

• Moving the topics around the TOC
• Opening the topics directly from the TOC

Moving the topics around the TOC

Let’s have a look at an example. The topic Home page was inserted incorrectly, and we need to shift it down and deeper into the structure, to make it a child of Customising HTML outputs.

Not really into dragging and dropping each topic precisely into its final position? You may like some of the methods presented below.

• To move a topic in the TOC, in the TOC Editor bar, use the arrows:

Copy and paste the topic from Content Explorer

1. In the Content Explorer panel, select and copy the topics you want to add to the TOC.
2. In the TOC Editor window, select Create a new item.
   A new TOC entry is created.

3. Use the TOC Editor arrows to move the new entry where you want to insert the topic.
4. Right-click the new entry, and from the context menu select Paste.
   The topic you copied is now linked to the TOC.

Copy an existing entry

Note: This method is recommended for the printed outputs where each TOC entry has its print-related settings. If a new TOC entry is created from scratch, you always need to adjust the default settings to match the whole document.
Meanwhile, copying and editing an existing entry keeps the properties consistent.

1. In the TOC Editor, right-click a TOC entry, and select Copy.
2. Move the mouse cursor to where you want the new entry, right-click, and select Paste.

3. If you need to move the new entry, use the TOC Editor arrows.

How to open the topics directly from the TOC

Are you one of those authors who use the TOC as document navigation, and sigh out loud each time when double-clicking an entry opens the topic’s Properties window instead of the topic? I was one, too, but changed the default Flare setting to a more convenient one 🙂

To toggle the double-click effect, in the TOC Editor, select the double-click behaviour button (See right) 
Now, if you double-click a topic node in a TOC, the selected topic opens in the XML Editor.

Managing the conditioning in MadCap Flare

Conditioning in Flare means marking the content to be included in or excluded from various outputs. Well-planned conditions certainly are one of the tool’s superpowers, and our tips will increase your working comfort and speed!

This section covers the following actions:

• Accessing the conditioning window
• Applying the conditioning on a live preview

How to access the conditioning window

When creating new content, it’s best to apply conditioning on the fly, without interrupting the creative process. Two methods are available for accessing the Condition Tags window without leaving XML Editor:

1. Use the shortcut Ctrl + Shift + C.
2. Right-click the content, and from the context menu select Conditions.

How to apply the conditioning on a live preview

With many products to document or several audiences, your topics and their conditioning may grow pretty complex. What if you want to proofread just the content that the users of your Product X will see? Luckily, you can set your editor to show you just one information set at once. This is how you do it:

1. In XML Editor, from the topic toolbar, select the select conditioning icon (See below)

2. From the condition tag sets, select the conditions to include, exclude or display by a media query.

3. Select OK.
   XML Editor now displays only the content you want to include.

Peer reviewing and tracking your team’s work in MadCap Flare

If you work in a team, you probably already know Flare’s Review ribbon, which contains the editor’s tool set – options for tracking, accepting and rejecting the changes, as well as commenting on the text.

Sometimes, however, you may want to share a PDF with someone without showing off all the glory of your internal comments. Flare’s got you covered!

How to toggle review changes in the outputs

1. From the Project Explorer, open the target where you want to hide or show the review changes.
2. In the target, go to Advanced > Output Options.
3. If you want to show your review changes and annotations, select Preserve tracked changes.

4. If you want to hide your review changes and annotations, clear Preserve tracked changes.
5. According to the option you selected, the target will now either show or hide your tracked changes.

Using the advanced search features in MadCap Flare

The search and replace functionality is one of the writer’s best friends, and it deserves its place in our tips and tricks review. Here are a few editor’s top picks from the Flare’s Find and Replace in Files pane:

• Find Text  > Options > Wildcards
  An option that lets you find specific text patterns in your documentation.
  To learn more, see MadCap Flare help: Wildcards
• Find Text > Options > Regular Expressions
  A powerful option that lets you find and replace complex text patterns in your documentation.
  To learn more, see MadCap Flare help: Regular Expressions
• Find Elements
  A relatively new feature that lets you search for HTML tags, attributes, and MadCap-specific elements, such as drop-downs.
  On the pre-defined elements, you can also perform a set of actions, such as replacing, wrapping an element in another element, or unbinding an element.
  To learn more, see MadCap Flare help: Finding and Replacing Elements

Note:  If you prefer using search in Flare’s internal Text Editor, make sure to check our post about editing the documentation portal’s front-end in Flare!

We hope that our series has been helpful in your day-to-day authoring tasks! If you would like to share some of your MadCap Flare knowledge with us, we’d love to hear from you. Perhaps we can create a bonus post together and share our readers’ favourite tips and tricks with the wider audience.

Are you in need of advice tailored to your specific needs? We are happy to provide MadCap Flare and Lingo consultancy.