Single Sourcing with MadCap Flare – Part 1: Overview

Flare is a single-sourcing authoring tool but if you’re new to Flare or single-sourcing in general, what that means may not be completely clear. That’s the subject of my upcoming series of blog posts.

In this post, I’ll define “single-sourcing” and briefly list Flare features that support it. In later posts, I’ll go into the features in detail, focusing on their mechanics, obviously, but also on their effects on project design. I’ll end the series by looking at how single-sourcing can affect project management.

What is Single Sourcing?

Single-sourcing is the creation of one source of content that can be used in multiple outputs (or, in Flare terms, targets).

Let’s say that you need to create a sales procedure manual in online and print form. You can create two projects to do so, one for the online and one for the print, but that has some obvious drawbacks.

• You have to write the content twice.
• You have to make any changes twice, once in each project. Eventually, inevitably, you’ll make a change in one of the projects but forget to make it in the other one.

Single sourcing fixes these problems.

• You can create one source of content to use for both outputs, or select a sub-set of the content for each output. For example, let’s say that you have to create a sales procedure manual for use in the US and Canada. Some of the content might apply only to the US, some might apply only to Canada, and some might be common to both. So you can generate one manual that contains all the content and tell the US users to ignore anything marked as applying only to Canada and vice versa, or better yet, extract the common content and the US content to create the US manual, and the common content and Canadian content to create the separate Canadian manual. But no matter which approach you take, it’s still only one source of content.
• You can create re-usable chunks of content and share them in different outputs. For example, the same screen shot and description might be used in different outputs from the same project, or even different outputs from different projects. Rather than writing that content multiple times, one in each project, you could write it once and re-use it and automatically change it everywhere if the content changes.

The basic concepts are that simple.

Overview of Single-Sourcing Features

Flare offers a bunch of features that support single-sourcing. Here are the major ones.

• Conditions – Conditions are categories. To repeat the US/Canada example – you have to create a sales procedure manual for use in the US and Canada. Some of the content applies only to the US, some applies only to Canada, and some is common to both. Conditionality lets you define “US only” and “Canada only” categories. (Content common to both audiences is always used, so it doesn’t have to be put in a category.)
  
  To create the US output, you tell Flare to exclude anything set to “Canada only”. The output will contain the common and US content but not the Canadian content.

• Placeholders (variables and snippets) – Placeholders are for repeated content. For example, say you’re documenting a new application whose pre-release code name is Longhorn. You write the word “Longhorn” hundreds of times in the content. Then marketing changes the name to “Vista”. You now have to search for all instances of “Longhorn” and replace them with “Vista”. Easy – do a search and replace. But what if you misspelled “Longhorn” several times. Search and replace won’t fix that. That’s where placeholders come in.
  
  The simplest placeholder is the variable – text-only. So, in the example above, rather than typing the product’s name constantly, you’d create a variable called, for example, productname, and set its value to “Longhorn”. You’d then tell Flare to insert the value of the productname variable and what seems to be the word “Longhorn” appears in the text. When the name changes, just change the value of the productname variable to “Vista” and Flare automatically changes the wording everywhere that you’d inserted the variable.
  
  A more powerful placeholder is the snippet. Unlike variables, which are text-only, snippets can contain anything that you’d insert in a topic, including variables.

• Flare Import File – Placeholders let us insert repeated content in multiple topics (and other files – discussed later). The Flare import file feature takes that one step further to let us share repeated content and files in multiple projects. You designate one project as the master and put all the shared files in it. You then create the child “real” projects and specify that they download and use the shared content and files from the master project. The big advantage of this feature is that child projects maintain an active link to the master. If a shared file differs between the master and child project, either because the owner of the master project changed the shared file or the author of the child project changed it, Flare will automatically download a copy of that file when the child project author builds the output. This overwrites the version in the child project and ensures consistency.

• Conditionalized styles – Most projects use one stylesheet but several Flare features can extend that. For example, you can create two stylesheets for a project and specify that stylesheet A is to be used for online targets and B for print. More efficient is to create one stylesheet and allow stylistic variations in the targets by using Flare’s medium feature. Finally, you can create one stylesheet and use the mc-conditions feature in the Stylesheet Editor to literally turn a given style on or off for a particular target.

• CSS variables – There may be cases where you want to apply the same value for multiple styles, such as color. You might specify the same color for h1, h2, and h3. However, specifying the color multiple times makes it easy to make a mistake. You might type the wrong digit in a hex-value color specification, for example. One solution is to specify the color in the body style, which propagates it down to all the subsidiary styles, but this might still be a problem since you’d have to specify the alternative colors for h4, h5, and h6. The CSS variables feature eliminates this issue by letting you specify the color in one variable and then call that variable for use in different styles.

Other features could be described as supporting single-sourcing, such as the Easy-Sync feature for importing Word and Framemaker files, responsive output and responsive layout, the Clean XHTML target and the Remove MadCap Styles feature in the Target Editor, and others. I’ll discuss all these features in more detail in upcoming posts.