Condition Guidelines for Flare Projects: Part 1

Applying Conditions

Conditions – how do I love them? Well, let me either count the ways, or count the duplicate, missing, unused, and capricious conditions that have made their way into our shared files. As soon as we began linking up our Flare projects and passing them around, it became apparent that someone was going to have to cut us off.

Some one had a condition for every reviewer: Joe, Mary, Tim. I had one for every status: To Edit, To Be Reviewed, Approved. I fought for that as a separate condition set, since it was convenient for seeing at a glance which files needed work. I was finally convinced to use a separate TOC for topics-in-progress. Like, duh.

And let’s not forget the conditions that were duplicated across multiple condition sets—some files had Print Only from applied from the Default set, others from the custom project set. I’m not looking forward to rooting those out.

After several combined hours of discussion, the some department guidelines were born. This first post covers our guidelines for applying conditions. In the second post, I’ll give our guidelines for defining target conditions and managing condition sets. These guidelines were written by our manager. The peanut gallery is all me. And if you’d like another good overview on Flare conditions, check out Paul Pehrson’s post about them. They seem to frazzle him less than they do me, though I don’t know if anyone can love conditions like I love conditions. That said; here are our guidelines:

Whenever possible, write around the need to use conditions.

• For example, if your text refers to a “chapter” or another type of text that is appropriate for a user manual, do not condition it out for a Help system. Rewrite the text to be applicable in both.
  This might seem to defeat the purpose of having conditions, but the more conditions you use the more likely that somewhere the conditions are at odds with each other. Each place that you apply a condition is a place that you have to check whether the outcome is what you expected.

When conditioning an entire topic or group of topics, apply the condition in the Content Explorer pane (not in the TOC). Do not apply conditions in the TOC.

• Talk of this rule started when we realized that applying conditions to the TOC did not remove them from a .chm or WebHelp build. That works to condition content out of a Word or PDF output, but in a help file, the topics will still turn up in a search.
• Additionally, some folks were applying the conditions to the files in the Content Explorer, as they should, but then also applying the same conditions to the TOC, for good measure. This was an unnecessary step, and also misleading for someone coming into your project.
• Actually, I would rather we took a stand on only having a single TOC, in which case we might have need for using conditions on the TOC. But since we are going with the rule for a few months, I will give linking TOCs another try.

Avoid applying conditions within a topic or to sections of a paragraph.

• If applying a condition to a complete paragraph within a topic (preferred use), apply the condition using the paragraph indicators on the left side of the screen. Applying and removing conditions in this way will ensure the underlying code is managed correctly. Two main reasons for this one. First, sometimes you have to go into the code to completely remove a condition. Better not to condition at the sentence level if you can avoid it. Second, if you are linking projects, importing a file only executes your topic-level conditions. For example, if you import a topics from a slave project based on whether they have the X condition applied, great. All the files with the X condition are applied. If you have the Y condition applied to all the Y product names within those topics, you can’t filter those out until you build a target. Each target can only use one combination of conditions. So if you are combining X and Y files into one target, they must have the same condition requirements.

The “NOT for USERS” condition is only to be used at the topic or folder level. Do not use it at the paragraph level.

• Inevitably, when trying to condition something as not for clients at the sentence level has come back to bite us.
  When a project has almost two thousand topics and a lot of conditions, some other condition is going to bring that content to the surface.

Okay, so once you have the perfect conditions applied with finesse and restraint, what next? Tomorrow I’ll post about defining how your targets use conditions, and about how to manage multiple condition sets in Part 2 of this post.