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:

five-ways-part-5-1

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.

five-ways-part-5-2

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:

five-ways-part-5-3

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.

If you have any questions about best practices for including conditions in your MadCap Flare projects, please feel free to reach out to me on Facebook or on Twitter at @MadCapDocTeam. Thanks for reading!

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

About The Author

Paul Stoecklein

About Paul Stoecklein

Paul Stoecklein has over 20 years of experience as a writer, editor, and documentation specialist. In that time, he has worked for a wide range of companies, including Anheuser-Busch, Edward Jones, and eHelp Corporation. Since the formation of MadCap Software in early 2005, Paul has headed its documentation department.

Last Modified: February 25, 2016

This entry was posted in MadCap Flare, MadCap Software, Tech Comm, Tips & Tricks. Bookmark the permalink.

Comments

  • Riley VanDyke February 25, 2016 at 10:34 AM

    A few things I find very helpful when working with conditions:
    ■ Design and implement condition tags *strategically*. Especially if a team of writers is working on the same content, NO single writer should create a condition tag on the fly. Condition tags should be carefully managed as a coherent whole lest one end up with a snarl of interlocking ad hoc tags all over a project.

    ■ Look for opportunities to apply condition tags at the more visible TOC entry or topic file level rather than within topic files. Sometimes there’s an inescapable need to conditionalize a piece of text within a topic file. But those conditions can become “invisible” to other writers who have no idea they’re there; tags at the TOC and topic-file level make it easier for everyone, including oneself if one hasn’t worked with a particular project in a while.

    ■ Append the word ONLY to condition tags to make it clear to everyone, including oneself, that the condition applies to content that goes in one specific deliverable. Sounds simple but it has helped me preserve my sanity many times.

  • Joe Srednicki February 26, 2016 at 8:20 AM

    I agree with the concept, but I would state it more succintly. You must decide the smallest unit or chunk where you apply a given condition. The smallest units that are efficient to administer when applying a given condition are (1) sentences and (2) paragraphs. As the example above shows, it can get confusing when you use multiple conditions for individual words within a sentence.

Have Something to Say?

Your email address will not be published. Required fields are marked *