Variables are extremely important in Flare projects. You might find that you use only basic variables, such as your company name, phone number, version numbers, or other general information. On the other hand, you might need to have a great many variables for different uses. In addition, you might need to use system variables (e.g., headings, date, time) in certain places.
[Menu Proxy — Headings — Online — Depth3 ]
Variable Sets
Custom variables are stored in variable sets, and it’s possible you might need only one variable set to hold everything you need. However, the more custom variables you have, the more likely it is that you will want to create multiple variables sets to keep them organized.
Conditions Versus Overriding Variable Definitions
You might be tempted to insert many variables of the same type (e.g., product names) in a topic and then place conditions on each variable in order to separate them at the time you build a target. This is not necessarily wrong, but you might find that it is more efficient to use just one variable and then override the definition as necessary for your various targets.
Example You have a project where you are writing documentation for five company products—Product A, Product B, Product C, Product D, and Product E. Instead of typing the name of each product manually throughout your project, you use variables for each one.
Now suppose you have a topic that is relevant to all five products. So you create five separate conditioned paragraphs (which is better for translation purposes than one paragraph) and insert the variables at the correct location.
This certainly will work, but there is a simpler way to do the same thing. Instead of five variables (and five paragraphs), you can create just one, perhaps naming it “Product.”
Then in the topic where all five variables were inserted, you use this one variable instead.
Then in each of the five targets, you override that variable definition with the name of each product.
So the target for Product A would look like this:
And the target for Product B would look like this:
The targets for Products C, D, and E would likewise have the variable definition customized. This means that you always insert the same variable in topics and snippets, regardless of the product(s) affected, and the correct name is automatically shown when you build a certain output.
Multiple Variable Definitions
You can also add multiple alternate definitions to a variable, using them as a way to override variables on a target.
This is not necessarily better nor worse than the other method for overriding variable definitions described above. It is simply another alternative.
Example Your company might have multiple phone numbers. You can associate them all with the same variable and use the appropriate one wherever necessary.
When a variable has multiple definitions, cells of the non-default definitions are grayed out (except for the definition cell).
The default definition is determined by the order of creation. The first definition created is the default.
In the target, you can then override the default definition with any of the others that were created.
What the MadCap Documentation Team Does
Our variables are organized into the following sets:
- Other These are general variables, such as company information (address, phone), product names in various formats (e.g., regular, all caps, lowercase), user guide titles, version numbers, and the year.
- Outputs These are variables with names of all the output types available in Flare.
- PDF-URLs These are URLs to all the PDFs that we produce. They are typically used in template pages and some micro content snippets.
In the “Other” variable set, we have a couple of date/time variables. We have one variable called “LastUpdated,” which uses the following format:
MMMM dd, yyyy "at" hh:mm tt
This variable is inserted at the bottom of a topic that automatically displays the day, year, and time when the output was last generated.
We also have a date/time variable called “Yr,” which uses the yyyy format. This format simply displays the current year (e.g., 2024) automatically whenever output is generated.
We never need to update either of these date/time variable definitions because they are always generated automatically when we build the target.
There are other variables that are entered once in a variable set (e.g., Product, User Guide Title) with a random definition provided (e.g., Flare, Getting Started Guide).
However, in each target we override that variable if necessary by simply renaming the definition by typing it.
And there are other variables for which we have provided multiple definitions. This is the case with some our variables that provide PDF URLs. For example, from many products we generate a “Shortcuts” PDF cheat sheet. The variable name is “Shortcuts,” but we provide a different URL for the PDF of each product.
Then in each Shortcuts target, we select the appropriate product URL.
