Experiences with variables

If you are a member of a work group, it is very important that the variables you use are standardized. All members of the group must use the same variables so that the information elements can be reused across the group, and for all publications.

In my publishing system we used to have a relatively large number of variables. All were documented in a separate "guide" which we sent out to all translators.

A large amount of variables, and the fact that they are often used in many information elements, means that it is sometimes a tedious job to ensure that all the necessary values are defined and imported when a book is ready to be published. It is true that our tool clearly informs you if something is missing, but it is sometimes felt as an unnecessary burden when you have to search for definitions that you have not used, and perhaps have no relation to.

This is just one of many practical experiences after working for a few years with variables in my texts.

Standardize!

All the variables you use must be standardized. It cannot be possible for individual members of the writing community to define variables. This must be an administrator task. Without a standardized system, it is impossible to establish effective reuse.

Communicate!

All variables must be communicated to all members of the writing community. Each author must have a clear understanding of how the variables are used, and what the purpose of each of them is.

All variables must be documented. This means that a written description of each variable must be prepared. The description must explain what the variable 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.

Be restrictive!

Choose carefully which variables you want to establish. It is smart to be restrictive. Using variables is a very efficient function, but if a writer has to deal with variables that are unknown it becomes tricky. If you need to define and import a lot of unknown or unfamiliar variables to start a publishing job, you're on the wrong track.

Limit the number!

If your publications shall be translated, 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 variables that are unknown, and these may have 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 a number of discussions with our translators. After listening to their arguments and advice, we removed most of the variables from our texts.

Tip

If you work with DITA publishing, you probably know that DITA has excellent support for using variables. You will find more about this under the heading DITA variables.

All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.

The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.