April 28, 2014

Managing Variation in Reused Content with Conditions

In part 1 of the Managing Variation in Reused Content series we investigated the basic technique of Injection, in which interchangeable names are extracted from topics and stored as variables, which are then injected back into a given topic when it is published. Injection is extremely effective in some situations, but many content variations are more complex and require a different approach. A more versatile technique is the use of conditions.

managing_variations

Part 2: Conditions

Conditions are suitable for parts of a topic that are only to be included in some of the publications that use it. Consider a user manual for washing machines. One topic describes the available programs that the washer can run. We simplify reality a bit and pretend that the only details provided for each program are temperature and time. The same manufacturer has a whole range of washers, and most of the program information is similar for all washers. Since the differences are small, can the same topic be reused for all washers?

Some differences can be managed using injection. For instance, each program could be assigned two variables containing the correct temperature, and program length. When the manual is published, the correct information is included depending on which machine it is intended for.

Screen Shot 2014-05-28 at 10.44.43 AM

But if the set of available programs differs between machines, injection will not get the job done. Let us say that some of the washers have an “eco-program,” which requires less detergent and less energy consumption. In this case, an entire row in the program table should either be included or not, depending on which washer is being described.

The solution is to tag the table row with a condition. We define a variable: “has eco-program”. The value of this variable is either “true” or “false”. We assign the default value “false” to the new variable, so that it will be false for all washers that do not say otherwise. Next we go into the configuration of all washers that have the eco-program function, and set the value to “true” for only those washers. Finally we go to the table row and add a condition that only consists of the variable name “has eco program”. When the manual is to be published, the condition is evaluated and the row is only included when the value is “true”.

The source for a very simplified program table could look something like this:

Screen Shot 2014-05-28 at 10.48.58 AM

Best Practices

A common mistake when using conditions is to base them on something very general, like product name. We could indeed use the product name to achieve the same result as above. Assume that there are five washer models, and only one of them — the latest one — has the eco-program. The name of that model is “W200B”. Why not change the condition to the product name, like in the next picture? After all, if we use the product name for all conditions we will not need to manage so many variables.

Screen Shot 2014-05-28 at 10.51.03 AM

 

 

However, the drawback of using product names in conditions is that it makes documentation more difficult to manage in the long run. It may look easy as long as there is only one washer that has an eco-program, but what happens when the next washer model hits the market? Someone would have to go through all conditions in the manual, and for each one check whether or not the new product name should be included. It could soon look like this (and it can get much worse):

Screen Shot 2014-05-28 at 10.51.17 AM

Another problem is that the product name could change, or the same product could have different names in different markets. Conditions relying on the name would be broken in such situations. In most cases, pinpointing exactly what function or feature is causing the variation in the manual and using a true/false variable in the condition is the best way to keep the documentation manageable in the long run.

There is another, less tangible, reason why it is better to use true/false conditions. A value must be provided for each variable used in the manual, per product model. (Though it is possible to simplify by assigning the default value false to those models that lack a given feature). This means that each product model gets a configuration description which lists all of its features. We sometimes refer to this as the product recipe. At first it can seem like extra work to maintain the recipe in addition to the text itself, but it often turns out to be a very useful tool. The recipe contains all the vital knowledge about product models and which features they do or do not have. It is used as a product reference by technical writers, and is often a central component in integrations with other IT systems. If all conditions were based on the product name, that valuable resource would not exist and the technical writers would have to examine complicated conditions in order to understand how different product models are configured.

Another very common mistake used when introducing conditional formatting is to apply the condition to segments of the text that are too small. Sometimes it is possible to squeeze in a condition where it is either not helpful, or risks causing problems later on. Here is an extreme example:

What is going on here? We have a line of text that describes how many batteries there are in a battery compartment. The actual number of batteries is defined in the variable “number of batteries,” and injected into the text using a reference to the variable. Next someone realized that the verb had to agree with the subject, so a condition was added. Now if there is only one battery, the verb form “is” will be used. Otherwise the verb form will be “are”. Clever right?

Too clever—even if one does not look at the word “batteries,” which becomes ungrammatical if there is only one battery. Conditions like this really do appear out there, but they make the source harder to understand, and they will stab you in the back when it is time to translate the document. In our experience, two guiding principles should be used to make sure conditions are applied to a suitably sized chunk:

  1. The condition should make the source easier to understand, not harder. One important benefit of reusing content is that it makes it possible to collect all knowledge about a topic in the same place. If overly complicated conditions make the source hard to understand, that benefit is lost.
  2. Never use conditions that are likely to make translation hard, or even impossible. Generally speaking this means no conditions that mess around inside sentences.

Instead of the convoluted example above, this would be much easier to maintain:

Screen Shot 2014-05-28 at 10.51.40 AM

If that is not possible, consider doing this instead:

Screen Shot 2014-05-28 at 10.51.48 AM

This article has shown some examples of how conditions can be used to manage variation in reused content, as well as given some pointers about what to avoid. The same ideas can be applied in other situations, such as customer specific adaptations. But sometimes other techniques give a better result, such as using version control to manage variation. More articles will follow in this series to cover these cases.

Did you miss part 1 of the Managing Variation in Reused Content article series? Read it here.  And be sure to browse our blog  for even more articles written by our talented team here at Excosoft.

About the author

Joakim Ström

With over 15 years dedicated to software development, Joakim expertly drives internal improvements and often hands-on innovation here at Excosoft.

Post Comment

Categories

  • Excosoft
  • Information Design
  • Skribenta

Latest posts

Looking Back on 2016

December 29, 2016

Skribenta 5 Now Released

December 12, 2016

What is a Topic?

November 4, 2015

More from Blog & News