April 30, 2014

Managing Variation in Reused Content with Injection

For technical communicators, the concept of reusing content is easy to understand. Chunk the content up into smaller, self-sufficient units that can be used independently of context, then combine the units as needed to assemble different documents. This is the fundamental idea behind topic-based authoring. One question that often comes up is, how small or large should the chunks be? This can be approached from two different angles: by considering either what is relevant for the reader, or what is practical for the writer. Ideally we should only consider the needs of the reader, but is that really possible? It depends upon the answer to another question: how is variation managed in reused content?

managing_variations

Can a chunk of content be reused, even if slight changes are required to adapt it to different contexts? Variation in technical documentation occurs for many reasons, and the best strategy for dealing with it varies accordingly. Some common reasons are:

  • The same topic is used to describe a common function shared by a variety of products or models.
  • The same topic evolves over time, either in response to new releases of a product, or because the document itself is revised.
  • The topic describes a product or service that is configurable and/or customizable.
  • The product is sold globally, and thus subject to variation due to differences in local laws or cultural norms.

How can such topics be reused, and yet made readily adaptable to different contexts? This article series, “Managing Variation in Reused Content”, will examine techniques and strategies for managing variation, explore their consequences, and discuss best practices.

Part 1: Injection

Injection is the most basic technique for managing variation. Consider a topic that describes safety precautions. It is nearly identical to a number of products, so it sounds like an ideal candidate for reuse. There is only one problem: it must contain the product name, which of course is different for each product. In this case injection saves the day.

Instead of writing the product name in the text, a reference to the variable “Product.Name” is used in its place, thus rendering the topic completely generic. When the topic is seen in isolation, it is impossible to know which product it describes:

Safety precautions for <Product.Name>

 

However, when the topic is to be published, the variable is assigned a value from the current configuration. The value is then injected into the topic so that the published document contains the product name.

outputspecproduct

In theory, any content can be injected – lists, tables, images, and so on. Besides names, screen shots are often suitable for injection. When screen shots are used in documentation they sometimes multiply. The user interface that is documented looks different depending on the type of release and product configuration. Many screen shots are needed to cover all variations. Injection is an easy way to select the correct screen shot for each delivery of the documentation, without having to modify the topic when new screen shots are added.

Finally a word of warning. Injection is powerful in some situations, but it should not be abused. Injecting parts of sentences, let alone parts of words, is not advisable. Consider this sentence which may be part of an assembly instruction: “Secure the lid with four bolts.” In order to reuse this instruction for different products, the sentence can be made more generic using injection:

Secure the <Assembly.Cover.Name>  with <Assembly.Cover.Attachment>.

 

When the topic is used, the values are supplied:

Assembly.Cover.Name = “lid”
Assembly.Cover.Attachment = “four bolts”

 

The values can be modified, so sometimes the cover is not a “lid”, but a “cover”. Some products are secured with screws instead of bolts, and the number of bolts/screws varies. Injection of this type often risks the creation of ungrammatical sentences; but this example seems to work so long as the values supplied for the variables are reasonable. Still, there are two other drawbacks to injection. Firstly, the topic may become too difficult to understand by itself. It is one thing that the readers should understand a topic, but we also like the writers to understand it so that they can maintain it. Secondly, chopping up sentences like this makes them difficult to translate. The injected texts may affect translation, making it no longer possible to translate the topic as a self-sufficient unit.

The case of reusing sentences is better handled using another technique – conditional publishing. Stay tuned: more articles will follow on that, and other techniques for managing variation in reused content.


Click here for more articles by Joakim Ström, and our other experts 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

More from Blog & News