Reusing content of topics in the same and other projects

[Sandra Blaschke]

This is my first post in this forum. I searched for similar topics first, but found no matching issues. If I overlooked some thread that might be useful for our specific case, I would be pleased to find links.

We are using a Wiki to create and publish our user guides for several years now, but are currently searching for a more powerful tool. This is where Flare comes in.

We haven't found a solution for the following requirement yet. I made a sketch trying to illustrate what exactly we want. You can find it below. Each box illustrates a page (or topic in Flare speak). Parts of the content of the pages Parameter 1 to 3 should be displayed in other pages (topics) of the same project and also other projects.

At first we thought of snippets. But in most cases the exact content is only valid for a small number of projects, which would surely result in a snippet overload soon.

Do you have any ideas how to realise this requirement in Flare?

Thank you in advance.

[techwriter31]

I haven't actually used them, but you could investigate snippet conditions?
http://help.madcapsoftware.com/flare201 ... itions.htm

[doc_guy]

In Flare, any chunks of formatted reusable content belong in Snippets. While it may seem that a large number of snippets becomes unmanagable, you can mitigate this to some degree by organizing your Snippet folder into sub-folders, and by pinning the snippets you use most frequently at the top of the Snippet list.

As mentioned above, Snippet conditions allow you to exclude certain parts of a snippet in a given location, based on conditions applied to the content. I've used snippet conditions extensively, and they are very, very powerful.

[ChoccieMuffin]

And you might also want to separate your condition tag sets so it's really obvious which is a snippet condition (be disciplined and only use them for snippets) and ordinary conditions that you use for including or excluding content and topics in targets.

Snippet conditions are really powerful, and you can find yourself tripping over them, so do take a long look at the help for them. In brief, I have these three "rules" that I follow when using them:

Using snippet conditions at topic level
If NO conditions are set, all conditions are included.
If both Include and Exclude conditions are used, any conditions not set are INCLUDED.
If at least one Include is used but Exclude is not used, all other conditions are EXCLUDED.

[Sandra Blaschke]

Thank you very much for your suggestions!

We still find it hard to picture a solution with snippets, because of the number. We are speaking about approximately 120 topics meaning 120 snippets per version of a documentation. This specific structure applies to 4 different software products with about 3 to 4 minor versions per year. Some of them are translated into a second language. So the initial number of snippets would be about 720 - not including any versions.

Speaking of bilingual projects: Do snippets behave like regular content when it comes to version control with GIT?

[Nita Beck]

Speaking of bilingual projects: Do snippets behave like regular content when it comes to version control with GIT?

A snippet file can be version controlled using Git just like any other XML-based file. A snippet file is actually no different under the hood from a topic file.

[NorthEast]

Why would you have 720 snippets?
You'd presumably have one snippet for each "parameter". Each snippet would include content for all the products/versions, and you'd apply conditions to the product/version specific content inside the snippet.

We still find it hard to picture a solution with snippets

Snippets are the only solution available in Flare to reuse content, if you want to (a) insert blocks of content in multiple locations, and (b) apply conditions within that content.


Perhaps create a real test project and create some snippets and conditions. It might be easier to visualise what you are trying to do with a real example.

[Sandra Blaschke]

A snippet file can be version controlled using Git just like any other XML-based file. A snippet file is actually no different under the hood from a topic file.

That is good news! Thank you!

Why would you have 720 snippets?
You'd have one snippet for each "parameter". Each snippet would include content for all the products/versions, and you'd apply conditions to the product/version specific content inside the snippet.

We have about 60 types of parameters and 60 types of time series per product (total number of snippets = 120). Only a small part of them are identical in all 4 products - lets say one out of four (=360). Half of them have to be translated into a second language (=540).

It's good to hear, that we can control the snippet version with snippet conditions. I'll try that. Thank you, too!

[NorthEast]

We have about 60 types of parameters and 60 types of time series per product (total number of snippets = 120). Only a small part of them are identical in all 4 products - lets say one out of four (=360). Half of them have to be translated into a second language (=540).

It's good to hear, that we can control the snippet version with snippet conditions. I'll try that. Thank you, too!

If you haven't yet looked at conditions and how you can use them with snippets, then you're missing a very important piece of the picture.

You can mark content in the snippet with conditions, and then decide whether to show/hide the conditioned content in your output. For example, a single snippet could show different content in two different outputs (targets), two different topics in the same output, or even two separate instances of the snippet in the same topic in an output.