September 11, 2014

Managing Variation in Reused Content with Version Control

In part 1 and part 2 of the Managing Variation in Reused Content series, we covered two basic techniques: Injection, and Conditions.  Injection is a method where values, or small pieces of text— often names or measurements— are extracted from topics, and stored as variables. When the topics are to be published, the values are loaded from the appropriate variables and injected into the correct place in the text. Conditions function as filters, sifting through parts of a topic, and adapting it to a given context. 

The idea behind both of these techniques is to store the generic knowledge of a topic in one place, as a single reusable topic. Specific details, such as product names and values of different kinds, create context for the topic, and are stored in variables. The context is the counter part of the topic: it holds all knowledge about a specific variation, such as a product model or customer specific configuration.

These single sourcing techniques go a long way, and will often be enough. But in some situations, single sourcing is not practical.

When a Product is Heavily Customized

Injections are great for substituting a variety of names and values in a topic. Conditions are equally great when it comes to managing parts of documentation that relate to specific product features whose presence varies according to different configurations. However, when variation in a topic is unpredictable and unstructured, neither technique works very well. This situation typically occurs when a product is heavily customized.

For instance, what should the documentation team do, in the midst of a large customization project, when presented with the task of delivering documentation for a product which is tailored to each customer, where each customer has a unique solution created on top of the standard product? The solution depends on the customer’s requirements, which can be quite unpredictable.

Let’s look at a software product— a document management system (DMS)— to find some examples. When the user registers a document in the DMS, a classification code is supplied. The meaning of the code differs from customer to customer, and so does the set of permissible values. In the standard product this value is optional, but in some customized systems it is required. Here are just a few variations of the description of this field in the on-line help:

Managing Variation w Version Control 1

Furthermore, another customer may have removed this field completely if it was not relevant to their business processes.

Considering the benefits of single sourcing, perhaps the answer is to put all customized texts inside conditions, and filter out the right variation of the topic, depending on which customer it is for. In a previous article in this series I wrote that conditions should be specific, and preferably based on a variable that can only produce true-false values. I also explained why conditions should typically not be applied to parts of sentences.

Keeping that in mind, we get these conditions:

Managing Variation w Version Control 2

This may look manageable, but there are a couple of drawbacks to this approach:

  1. Most obviously, a new condition will be needed for each customer that requires a customized description. There is a risk that the source documentation will become so cluttered with customer specific conditions, that it will be hard to maintain.
  2. Putting all customizations together like this doesn’t add any value— it does not produce any meaningful knowledge. On the contrary, it gets more difficult to understand both the standard product, and each unique customization. In this case more value is achieved by gathering knowledge about each customization, rather than squeezing them all together.
  3. From an organizational point of view, reusing the same topic for all customizations means that each project will have to share and update that topic. Often one department is responsible for the standard product and its documentation, and each project is responsible for customization. Forcing the customization projects to work in the same source files as the product development team is often a bad idea.

Back to Basics with Version Control

The right approach in this scenario is often to use a separate version branch for each customization. A version branch is essentially a copy of the entire source documentation, which the customization project can modify freely without interfering with the standard documentation. This might seem like a step backwards—copying source files is the opposite of single sourcing, and this was how variation was managed before the days of XML production systems—but that is just how it appears.

One of the fundaments of this series is that the purpose of single sourcing is not to reuse text, but to reuse knowledge. For the achievement of other ends— such as the reduction of translation costs— there are other, and better, means. Text is just the vehicle of knowledge, and although single sourcing techniques necessarily manipulate text, we should always keep in mind how those techniques help add value in the form of knowledge. This is the key to making single sourcing manageable and productive.

Using version control to separate projects in branches is fairly straight-forward. But one important question remains: will the customized product ever be upgraded to a later version of the standard product? In most cases this is not an issue. When the product is a machine, a nuclear power plant, or some other physical product, it cannot be upgraded, (although it may contain upgradeable software, which is increasingly the case).

If the customized product is a software product designed in such a way that it can be upgraded to a later version, without losing the customizations, the customized documentation will also need to be upgraded. This can be challenging, depending on the capabilities of the CMS. In this case, a function for integrating the customizations into a new version of the standard documentation is necessary.

The purpose of this article is to point out that in some cases single sourcing can be taken too far, especially if focus is placed on achieving the highest possible rate of text reuse, rather than on optimizing maintainability and productivity. It is not always easy to see exactly where that line goes, but it helps to keep it in mind.

Did you miss previous editions of this series? Read them here: Part 1 / Part 2.

And feel free 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


  • Excosoft
  • Information Design
  • Skribenta
  • Tech Writer Tips

Latest posts

More from Blog & News