This is the final article in a five-part series written by Paul Stoecklein, who has headed up the documentation department at MadCap Software since its inception, overseeing the development and publication of all online Help systems, PDF manuals, and video tutorials for all applications in the MadCap product family.
Conditions. Everybody loves them. Everybody uses them. At least they should.
Conditions let you flag certain content, and even entire files, for inclusion in (or exclusion from) certain output. They’re one of the cornerstones of single-sourcing.
You might already be quite familiar with conditions—how to create them, apply them, associate them with a target. But what you might not realize is that there is a way to work with them that may save you and others some headaches.
I’m talking about applying conditions to chunks of content, rather than in bits and pieces.
Let’s say you have a sentence like this:
Suppose the content in this sentence needs to vary slightly for eight different outputs. You want to be a good single-sourcing citizen, so you add your content for the various outputs in the same sentence, and you apply conditions accordingly. You even apply different conditions to the articles “a” and “an” so that the sentence will read correctly in the output.
This is what we in the technical communication industry call a “nightmare.”
It’s very hard to manage. Not only that, but if you need to get the documentation translated into five other languages, this content is going to make it really hard, if not impossible, on those translators.
So instead of trying to reuse every single character to the nth degree, it’s much better to do something like this instead:
You might be repeating some of the text—which I know is anathema to single-sourcing—but so what, it’s not that much text. And in the end you’ll be saving time—both yours and others—because you won’t spend lots of time trying to decipher what you were trying to do in that sentence.
Single-sourcing is a beautiful thing. For those of us in technical communication, it may even be the most beautiful thing. Just remember to use it wisely and not become a slave to it at the expense of everything else.
View the other entries in the series, Five Ways to Improve your Flare Project:
Five Ways to Improve Your MadCap Flare Project: Part 4—Master Pages for Different Topics
Five Ways to Improve Your MadCap Flare Project: Part 3—Using Thumbnail Images in Your Documentation
Five Ways to Improve Your MadCap Flare Project: Part 2—Using Drop-Downs in Your Documentation
Five Ways to Improve Your MadCap Flare Project: Part 1—Using Examples in Your Documentation
