MadCap Software Forums

Hi,

I've been hunting all over the forum and checked the conditioning white paper but haven't worked out if the following is possible:
I have a Procedures manual to list all the procedures for a particular product. There are some parts of the product that are very similar but have slight differences. Instead of writing the same procedure in multiple places to accomodate for the slight differences I have used one topic and applied conditional formatting.

If I was just going to include one of the conditions in the output that would be fine (I would tick 'include' for one and 'exclude' for the other). However, the problem comes because I use the same topic in 2 places but I want different conditions applied.
My thoughts were: Apply the conditioning to the topics at the ToC level, and then hoped that when built, Flare would grab the appropriate condition for each topic. The problem: it didn't work and Flare applied both conditions to both topics.. not what I wanted.

Incase all that didn't make sense, I'll try to use an example.

Say we want to tell the user how to configure the 'colours' for two particular types of Scans. I.e., we want to configure the colours for the Y scan and we want to configure the colours for the X scan. To do this is basically the same, except they have a few different options to select from and the titles are different. So, rather than having two topics saying prettymuch the same thing I put them in the one topic and then applied a condition to each of the 'things' that changed between each one. i.e., an image, a title etc.
Then, in the ToC I have the topic in two places (i.e., one section is for the X Scan and one section is for the Y Scan)... I applied the conditions to the topics in the ToC because I wanted one to show only X Scan info and one to show only Y scan info. When I built I originally didn't have any includes or excludes (i just included everything, or so i thought). That didn't work so i went and applied include to X Scan stuff and include for Y Scan stuff.. still no success, it puts both in both documents..

Do you know if I'm doing anything wrong? Or maybe it can't do it?

Any help would be appreciated please!

Thanks,
Avril

Is this a place where snippets might be useful? That way you could "build" two different topics from the snippets but still only have the one set of instructions. Just a thought, wait for the experts to give you a better answer.

You can do this with snippet conditions. Create a snippet with a conditions for your various requirements, place it in a topic, then set the snippet condition you want on the topic. (Topic Properties, Snippet Conditions tab).

However, it's very easy to get confused when using snippet conditions, as apart from the special way they can be applied at topic level, Flare treats them as ordinary conditions too, and you can re-apply them in the target too. This may possibly override what you intended to do, and could turn into a maintenance headache for someone in years to come. So, to avoid problems later, I'd advise:

• Create a separate condition tag set for snippet conditions.
• Include SNIPPET somewhere in the name of each condition, so you don't ever expect it to work like an ordinary condition, so aren't tempted to use it as such anywhere.
• When you place a snippet with snippet conditions in a topic, get into the habit of setting the appropriate snippet condition on the topic immediately, so you don't forget.
• At the top of each snippet that uses snippet conditions, add a "comment" (see below) saying that this snippet uses snippet conditions, and if necessary, what they are and what they mean, if not completely obvious. This will help remind you to ensure that you always set the snippet condition on the topic when you place the snippet in a topic.
• In each target, set all snippet conditions to always be included. This will ensure that you don't inadvertently exclude something that has been included as a snippet condition at topic level (which Flare will allow you to do, unfortunately). Anything that you excluded as a snippet condition in the topic where the snippet was placed will be excluded, regardless of what you set on the target, but anything that was included as a snippet condition in the topic can still be overridden at the target level.
• Don't get too adventurous. Just because you can do it in Flare, it doesn't mean you should do it. Think about how maintainable and extendable your solution is. Simple is best.
• Avoid snippet conditions unless absolutely necessary, because of the potential for problems later on. Often, I find that by rewriting my content a bit (to move the conditional bit to the beginning or end of the snippet) I can use a snippet without snippet conditions, and handle the differences in the text immediately before or after the snippet. I'm not saying don't ever use them - they can be very useful - just use them with caution to minimise the subsequent opportunities for problems.

How to do comments in Flare? I define a condition (not a snippet condition, an ordinary one), called COMMENT, that is always excluded from all targets. Then I can write any useful info anywhere in a snippet or topic, and apply that condition to it. I can see the "comment" when I'm working on the snippet or topic, but it never appears in any output. One of the places I always use a "comment" is where I have snippet conditions. This has saved my bacon more than once, and stopped me from making a mistake.

Msquared wrote:You can do this with snippet conditions. Create a snippet with a conditions for your various requirements, place it in a topic, then set the snippet condition you want on the topic. (Topic Properties, Snippet Conditions tab).

Thank you thank you thank you!
I have spent two weeks trying to understand this and it wasn't until you put that you define the snippet include/exclude differently (using the Snippet conditions tab) that it finally made sense. I thought I could only do an include or an exclude for a topic, not for snippets inside a topic too.
Genius!

Great suggestion with the comment too.

My query now is this:
In what situations do you think it would be wise or unwise to use snippet conditioning?

My situation:
I have two types of 'scans' that I am describing (just two ways to show information on graphs).. i have about 9 steps that are exactly the same except for the names of the scans and the images used. Everything else is the same. I want to use this topic in two different places; one place for the first type of scan and the other place for the other type of scan.

This is just one of several pages that do the same thing. To me there seems to be a lot of repeating information so I think I should, but before I go and get everything confused, I just thought I'd check..?

Thanks!

Your scenario sounds exactly the sort of case that snippet conditions were made for. So I'd go right ahead and make your snippet with the conditional text you require. Just make sure that you use a separate condition that is clearly named as a snippet condition, and that the use of the snippets with snippet conditions is clear and obvious to anyone who may need to maintain them or the topics that contain them later. Although snippet conditions are applied differently from ordinary conditions (as you discovered), when you come to specify the target conditions to include and exclude, snippet conditions look exactly the same as any other condition, and that's where the mistakes are going to be made later on, unless you take care now.

The only thing that may restrict your plans is the need to set the snippet condition at a topic level. So should you find that you need both variants of the snippet in the same topic, you would be stuck, as you won't be able to do that.

In that case, you could make two snippets, one for the first scenario, and one for the second, and place them accordingly. Of course, there is nothing to stop each of those snippets being a mix of smaller snippets which are shared between both snippets and content specific to that scenario.

Sounds great. I shall proceed with snippet conditions.. full steam ahead!

Thank you!

Msquared wrote: The only thing that may restrict your plans is the need to set the snippet condition at a topic level. So should you find that you need both variants of the snippet in the same topic, you would be stuck, as you won't be able to do that.

Darn. I was looking for a way to do just that. I was so proud of myself, having come up with a single snippet with multiple conditions that could be used for 4 different topics. Worked like a charm, until I needed to include 4 instances of the same snippet (with different conditions) in one 'index-like' topic. I got excited thinking it might still work because right-clicking on the snippet block bar gave me the Conditions option - not the snippet conditions though.

Such a shame I can only apply snippet conditions to a topic and not to a snippet block within a topic.

Back to the drawing board.