Snippets and conditions are two of the most important features in Flare Desktop, especially when it comes to single-sourcing content.
[Menu Proxy — Headings — Online — Depth3 ]
Organization
As is true with other kinds of files, the more of these you use in your project, the more important it will be to organize them. For snippets, that means creating subfolders in the Resources > Snippets folder of the Content Explorer. For conditions, it means using multiple condition tag sets in the Project Organizer.
Snippet-Focused Versus Condition-Focused Topics
Another important consideration when structuring your topics is whether to make them more snippet-focused or condition-focused. Although you are likely to use both snippets and conditions in your topics, you might give more weight (or focus) to one than the other.
Example You have a project where you are writing documentation for three company products—Product A, Product B, Product C.
You have a topic that is used in each of those products. The topic is made up of five paragraphs. The first two paragraphs are identical for all three products. The third paragraph is unique to Product A, the fourth paragraph is unique to Product B, and the fifth paragraph is unique to Product C.
Should you have one topic or three? What is the best way to structure the topic? Which features should you use?
You might choose to take a more condition-focused approach, or you might decide a snippet-focused approach is better. With either approach, this doesn’t mean that you are limiting yourself only to conditions or only to snippets; instead, it means that one of those takes on a more prominent role. If you use a condition-focused approach, you’re still likely to employ snippets in some ways, and likewise, if you use a snippet-focused approach, you will likely still have some conditions (e.g., online versus print).
Condition-Focused Approach
With this approach, you would have just one topic, and you would use conditions to include or exclude paragraphs for a given target depending on the product.
Therefore, the first two paragraphs would not need a “product” condition since they are needed for all three outputs (i.e., the target for Product A, the target for Product B, and the target for Product C). In those first two paragraphs, you might have just regular content, nothing more.
However, on the third, fourth, and fifth paragraphs, you would place conditions that are unique to each product.
Snippet-Focused Approach
With this approach, you would have three topics instead of one. The first two paragraphs in each topic would be snippets, since the content is the same in all three topics. However, the third paragraph in each topic is simply regular content that is unique to each product; no conditions are necessary on those paragraphs.
Which is Better?
An obvious benefit of the condition-focused approach is that you only need to create one topic instead of three. On the other hand, a topic with a lot of content can get confusing, especially when much of it has conditions applied. Figuring out which content goes with what might take more time and effort than you want. This can be especially important if you have new writers or need to send the topic to subject matter experts for review.
As for the snippet-focused approach, it can be much more straightforward when you need to return to it for editing or send to a reviewer. However, this approach requires you to create multiple topics instead of one.
There isn’t a right or wrong answer. Either approach can work nicely for your needs. It is recommended that you try each approach on a few topics to see which one you like best. In the end, the best choice is the one that is going to save you the most time and effort, and help you to avoid errors.
What the MadCap Documentation Team Does
At one time, we used a condition-focused approach. With this approach we created fewer topics, but over time we found that we were spending too much time on some of our shared topics, trying to decipher what all of the conditions meant and what needed to be edited.
Now we typically use snippet-focused topics. Even though we are creating more topics, we find them to be much easier to handle, especially since we have a very large number of conditions in the project. The more streamlined we can make the topics, the easier they are to handle, especially for a new author or a reviewer. The bottom line is that we found we were spending less time and effort on snippet-focused topics than we were on condition-focused topics.
Also, because we use a lot of snippets with this approach, we created a special subfolder next to our product subfolders, and we named it “Shared.” Within this folder, we created even more subfolders to store snippets that are used for multiple products.
We also set the appropriate product conditions on each snippet file. These conditions have nothing to do with our snippet-focused approach. Rather, these conditions are used when we import files into our child “Develop” projects using Global Project Linking.
