Single Source Best Practices Togglers vs Conditional Tags

[btwrites]

Hi, I'm fairly new to Flare and definitely new to Source Control. I have an online user guide that I may soon need to create different targets to produce new outputs. We now have customers who have multiple locations with different user functionality than customers with one location - thus, for the multi-location customers, there will be different screen shots and different content. I'm thinking about using Togglers - one for stand-alone offices and one for Multi-Location offices to deal with this.

I've also thought about using conditional tags, but the problem I have is that I have no idea who will need multi-location support and who will not. And, a single-location customer could expand offices and then become multi-location.

If I use conditional tags, I think it would be difficult to track where I put these conditions and it seems to me that the customer base (one office vs multiple locations) could change. So, I'm hesitant to use conditional tags in this case. And, I've worked with conditional tags and can see the pros and cons of it. Unfortunately, I didn't think though how these conditional tags might need to change (I originally set these up to track work flow progress - ready for review, complete, etc.) and now I regret that.

So, I'm looking for best practices - how do I keep my project to a single source while producing outputs that work for each customer? Are togglers best for this? The context of multi-location is pretty generic so it wouldn't necessarily need a variable.

Any ideas for best practices would be most appreciated. Thanks.

[Nita Beck]

Hi! There is a lot to learn about Flare, and we've all climbed the learning curve. Let's take some things one at a time, including terminology.

... I'm fairly new to Flare and definitely new to Source Control.

Be sure not to confuse single sourcing with source control. Single sourcing refers to the practice of using a single bit of content in more than one place, such as the same topic in both an online Help system and in a printed/PDF manual. Source control is something altogether different. So as not to confuse you, I won't explain source control here, but will just say that you are talking about single sourcing.

... I'm thinking about using Togglers - one for stand-alone offices and one for Multi-Location offices to deal with this.

I think you have a fundamental misunderstanding about what a toggler does. It is simply a mechanism to show or hide -- or perhaps think of it as expand or collapse -- content within a topic in a Help system. (Togglers are not relevant to print output in that sense that anything within the toggler will always be shown in a PDF.) For example, on this sample page from the Flare 10 Help system (http://webhelp.madcapsoftware.com/flare ... _Flare.htm), the short list of links near the top are all togglers. One can expand and collapse them individually, or one can click the "Expand all" button on the toolbar above the topic to expand them all at once. But togglers are not used -- at all -- to control what content is included in or excluded from generated output. That's exactly what conditions are for.

... I've worked with conditional tags and can see the pros and cons of it. Unfortunately, I didn't think though how these conditional tags might need to change (I originally set these up to track work flow progress - ready for review, complete, etc.) and now I regret that.

No worries. It is completely acceptable to have more than one condition set in the same Flare project. For example, in my projects, I'll have one condition set that I call "AuthorStatus," which includes conditions such as "Done," "In Progress," "In Review," and "Not Done". I'll have another condition set that includes "product" conditions, such as "ProductAOnly," "ProductBOnly" (where "ProductX" is the name or abbreviation of a product). And I'll have a third condition set that I refer to as "output" conditions, such as "PrintOnly," "ScreenOnly," "ReviewOnly," "AuthorOnly," and so forth. When I set up a target's conditions, I can easily define which conditions to include and to exclude.

Your instincts about being cautious regarding conditions is a good one, as one can get into a lot of trouble with the logic of the includes and the excludes. A best practice is to include the word "Only" in the name of a condition, as for some of those I listed above. Also, one needs to understand the "pecking order" of the conditions. Everything is included by default (so the Include check box doesn't need to be selected in the target; these are known as "implicit" includes). An exclude (Exclude check box is selected) trumps the implicit includes. Finally, an explicit include (Include check box is selected) trumps everything.

I suggest that you spend some time reading up on conditions because, truly, they are exactly what you need to accomplish your goal. You might find it easier to read the Conditions PDF than to read topics in the Help system. The PDF is at http://docs.madcapsoftware.com/FlareV10 ... sGuide.pdf.

I hope this helps. If you have more questions, just ask. We are here to help.

EDIT: Going off on a tangent here... You might want to look into the use of file tags to track workflow. Read more here: http://webhelp.madcapsoftware.com/flare ... agging.htm

[btwrites]

Thanks so much, Nita. All of this is very helpful. I meant to say single sourcing rather than source control - my bad.

The reason I was thinking of togglers is that I will not know in advance who will have multi-location practices and who will not - thinking then, that, the end user can choose to view the information contained in a multi-location toggler within each topic if in fact they have multiple locations. It would be easier to use conditional tags if I could know in advance which customers are multi-location and which ones are not.

I'll definitely read the PDF article and also the article about file tags - sounds like it would be very helpful.

Thanks so much for all of your help. I really appreciate it.

[kmorrison]

I'm in the same boat as you, btwrites. I have two versions of a product to document for multiple user types. As it is, we publish many versions of the documentation, and customers have to go down the list and figure out which one they need. It's a bit clunky, but I don't see a better solution right now.

It would be really nice to be able to produce a single help system with a switch (or a couple of switches), so that customers could indicate which situation applies to them, and see the relevant help. My goodness that would be nice.

[ChoccieMuffin]

Would it be wrong for single-site users to be able to see multi-site content, or is that strictly verboten? If not, then try this.

In the scenario below, you would format the drop-down head so that in your PDF medium it looks like the regular heading that it would equate to when printed (or create a series of styles such as dropdown head.H3, dropdown head.H2 etc so you can use this idea in several places)

You would either need to produce different printed outputs for the two different types of user (excluding the one you don't want to use), or perhaps add cross-references in your content that is conditioned as print-only, as shown.

"This section describes how to make hot drinks, such as tea and coffee.
{Condition to print only}
* For single-site users, go to [x-ref to the first drop-down]
* For multi-site users, go to [x-ref to the second drop-down]{end of condition}

{Drop-down head}Making tea and coffee{condition the next bit to PrintOnly:" - single-site users"}
{Drop-down body}Instructions on how to do it.

{Drop-down head}Making tea and coffee {condition the next bit to PrintOnly:" - multi-site users"}
{Drop-down body}Instructions on how to do it."

If producing different PDF outputs for the different users, instead of including a little condition in the drop-down heads, condition the entire drop-down and exclude the one you don't want, and don't bother putting in the first condition that includes the bulleted list.

Does that work for you?