Skriftlig Info ➜ DITA publishing ➜ DITA variables ➜ About variables in DITA

In many cases, a specific word, term or proper name (for example, the name of the product) makes it impossible for a fragment to be used in several places.

This gives us a dilemma.

• On one hand, it is often really useful to identify the product name, manufacturer or other unique terms in the text fragments.
• On the other hand, it is precisely such terms that inhbits reuse of the text fragments.

To reuse a text fragment in many different contexts, we use variables in the text.

Variables in a text can be compared to the variables defined in software. These variables are normally defined early in the source code, and used throughout the application.

At first: What is a variable?

Next: What is the difference between a variable and a value?

DITA has no separate element for defining variables. Nevertheless, we can use the keyref attribute to achieve the desired functionality. Depending on which publishing system you use, there is another option, namely the varref attribute. That's why I tend to say there are two ways to define a variable and give it a value.

1. You can create a topic map and use the <keydef> element.

   This is the usual way to define variables. In your topic, use, for example, the <keyword> element with the attribute keyref.

2. You can create a library topic and use the <keyword> element.

   You can also use other elements. Defining variables in this way requires that your DITA system supports the use of the varref attribute. This attribute is not defined in the DITA standard but is a widely used proprietary attribute. The use of the varref attribute, the <keyword> element, and possibly other elements is determined by the Document Type Definition (DTD) that you are using.

Both library topic and topic map can contain multiple definitions, and each variable can have any value you want.

The following suggestions for basic rules are based on several years of experience:

1. All the variables you use must be standardized.

   It cannot be possible for individual working group members to define variables themselves. Defining variables must be an administrator task. Without a standardized system, it is impossible to establish effective reuse.

2. All variables must be communicated to all members of the working group.

   Each author must clearly understand how they shall use the variables and their purpose.

3. All variables must be documented.

   A written description of each variable must be prepared. This description must explain the purpose of the variable, what it is used for, how it is used, and what kind of values it can have. Such documentation is important for internal use but even more important for those who shall translate.

4. Be careful when you choose which variables to establish.

   It is wise to be restrictive. Using variables is a very efficient function, but it becomes tricky if a writer has to deal with unknown variables. The same is the case if you have to bring in a lot of unknown variables to publish.

5. Be aware of complications with translations.

   If you translate your publications, variables pose a major challenge for the translators. You cannot assume that the translators are familiar with the functionality. The translator also has to deal with unknown variables, including values that are difficult to translate when taken out of context. We have also experienced that the values defined in different combinations can be difficult to translate because different languages operate with different grammatical genders. We had several discussions with our translators. After listening to their arguments and advice, we removed most of the variables from our texts.