There are many reasons why technical documentation has different variants. But what is the best way for a technical writing department to keep these variants under control? Stefan Gruber-Barowitsch – a Graz-based Technical Communication Consultant and Quanos partner – has revealed his approach to identifying the different variants in documentation.
In his model, there are several stages to identifying the variants. As soon as different variants are identified, they can be separated and managed in authoring environments as content modules. The advantage of this model for technical writing departments is that the level of detail included in the analysis can individually reflect the needs and capabilities of every authoring department. Not every technical writing department can handle the same number of variants. What is actually possible is determined by factors such as the documented products, the available human resources, and of course, the authoring system that is being used.
So what does this model look like? It always begins at stage 0, the standard that already exists in the technical writing department. This is because almost every company already has different document variants, and also manages them in one way or another. They are often stored in the file system or included in an Excel list, which notes the differences between the various instruction manuals.
During stage 1, the approach becomes pragmatic, looking at which sections are present in all instruction manuals, and how a uniform structure could be produced. The best way forward is to be guided by the table of contents in the various manuals, and mark which text segments are the same, as well as those that are different. It is a matter of identifying which sections are absolutely identical. You can then use these sections as standard sections for your documentation.
At stage 2, you determine whether for some variants, other sections need to be included in addition to the standard. We are still talking about section level here; it is only a matter of identifying additional, optional text segments.
You only start looking at the content in more detail at stage 3. Can you identify any self-contained units within a section that are only added for some variants? These text segments can then also be included as standards in variant management.
Stage 4 now focuses on illustrations. Which illustrations are identical in all instruction manuals, where should symbolic illustrations be used, where is it necessary to change illustrations, captions, and labels? In illustrations, it is sometimes the smallest details that are critical. This aspect of instruction manuals therefore deserves special attention.
We finally arrive at character level in stage 5. Some text segments are largely identical, although a few characters have to be replaced. Typically, this includes product data or product designations. For the sake of simplicity, many technical writing departments combine all product data for all products in a technical data table. But this scenario can quickly become difficult to manage. With the right authoring software, it is often a better solution to provide product data as variables, and change them where relevant.
By taking this approach, variants can be readily identified at different levels of the documentation. Last but not least, another quick look at the question of what is the point of all this variant management: Is it worth the effort that has to be put into it? Everything has always worked out in the past, somehow or other! It is certainly true that you can generally cope, one way or another. But with appropriate variant management, you achieve many objectives simultaneously. Your instruction manuals become more consistent. This makes them easier to translate. Less maintenance is needed, as changes only ever have to be made in one place. Your time-to-market is also shorter. As soon as the configuration of a new product variant becomes clear, you can quickly derive its associated documentation from that which already exists, and determine the amount of effort involved in creating the new instruction manual. It’s clear to see that the benefits of systematic variant management are felt at many different levels. All you have to decide is how much detail to include in your variant management