[Guest Post] “Levels of Re-use”, by Dr. Tony Self

At the heart of most advanced authoring and publishing systems is the concept of re-use. As the name implies, re-use means using the same piece of information in different places. Looking deeper, we can find that there are different levels of re-use, ranging from the superficial to the systematic.

Superficially, when you copy a paragraph out of an e-mail, and paste it into another e-mail, or a report, you are re-using that paragraph. However, that’s not what is normally meant by re-use in technical communication. Re-use is more properly considered to be re-using the original piece of content somewhere else without copying it. The original piece is used again through a method called transclusion, which is derived from trans (Latin, meaning across) and inclusion. Including a piece of information from one place across to another location, topic, document, or publication.

Transclusion is part of an ideal called WOOOWrite Once and Once Only. The theory of WOOO is there is an enormous amount of efficiency in writing something once, and maintaining it from that single location. If a suite of 100 camera manuals all carry a description of SD cards, then it saves time and money to write this piece of information once, and simply transclude it to the other places where it is needed.

Variables and snippets – features found in many authoring tools – serve this purpose. Another type of re-use is often overlooked. If you have a Help topic that is used in more than one place in a document, that topic can be referenced more than once in the Table of Contents (TOC). In other words, the same topic can be re-used in a second place simply by creating a second pointer to that topic. While there are many arguments against repeating the same topic in the one publication, it is much clearer in a single-sourcing environment, where many outputs are produced from the one source project, where there might be different TOCs for each output. So having a number of TOCs with common topic references is another type of re-use. So re-use is at the heart of single-sourcing, and single-sourcing reduces the cost of documentation.

The degree to which re-use can be implemented is determined by the smallest taggable element. For example, a word cannot be re-used unless it is wrapped in its own tag. Working backwards from that point, we can find four distinct types of re-use. We can represent these levels as a pyramid.

Four Levels of Content Re-use

4-levels of reuse

At the simplist level, re-use of TOCs, or topic maps (ditamaps in DITA authoring), may involve referencing one map in multiple maps. This allows a section of a document to be repeated across multiple documents. This is document level content re-use, where the unit of re-use is the topic map.

Perhaps the most common form of re-use is when one topic is referenced by more than one topic map, and therefore, the same topic is re-used in different content collections. This is topic level re-use, where the unit of re-use is a topic.

A block element within a topic, such as a paragraph or note, can be re-used in another topic through transclusion. (In DITA, this is called a conref, or content reference). This type of re-use is paragraph level re-use, where the unit of re-use is a block element.

The finest re-use granularity is phrase level content re-use. This involves using transclusions to re-use words or phrases (or inline elements) from one topic in other topics, where the unit of re-use is an inline element. Examples of this sort of re-use include product names, trademarks, and user interface labels.

Re-used phrases can be used within re-used paragraphs. Likewise, re-used paragraphs can be used within re-used topics, and re-used topics can be used within re-used ditamaps.

Being able to work comfortably with re-use is important for a technical communicator, but more critical is to develop strategies for managing re-use. Knowing that some content has already been written, particularly when working in a team, is the biggest or many challenges. But exciting challenges they are!

Below are links to his latest recorded webinar sessions with Tony Self: