Many documentation teams are already creating a large amount of duplicated content. But are they intentionally duplicated and managed, or is this content simply copied and pasted into 40 files that no one knows how to manage? Reuse of content is a practical matter and, while there are many tools to support it, it is not determined by the tools. The key is to define good, reusable content, and manage where it is and who can edit it.
The whitepaper will continue on in the following sections. Sizing content for reuse, for reusing it, for managing the variation that is produced by the reuse, and managing the reuse program so that it does not deteriorate over time.
Decide what counts as a reusable unit before you build anything
The main reason why reuse fails is that teams are chunking at the wrong level. They are either chunking too fine, leading authors to have to search for small pieces of prewritten content instead of just writing it, or too coarse, with every instance of reuse having to be excepted from the general rule.
While the three properties above can serve as a good starting point for sizing content for reuse, a more realistic test for content chunking is whether or not the chunks are, 1) Independent and useful on their own; 2) Able to be reviewed independently; 3) Stable (i.e. Rarely changed and all changes are intentional). Safety warnings, a product’s specifications, a hardware connection how-to, and a legal disclaimer all would qualify as reusable content. Chunked paragraphs that start with the words “As described above….” would not.
Audit before you restructure
Looking at the similarity of content elements within your current content is very eye-opening when it comes to determining potential components for reuse. Most organizations find that good candidates for reuse are items such as safety warnings, prerequisites to procedures, definitions for a glossary, and common boilerplate text. More complex procedural content can also be chunked for reuse by authors after they have bought into the concept of reusable content.
Choose a reuse mechanism that matches your scale
Content reuse mechanisms can be categorized based on degree of overhead (over-and-beyond normal document management) and degree of ceiling (limit to what can be reused).
| Mechanism | Best suited to | Main limitation |
| Shared snippets in an authoring tool | Small teams, under a few hundred pages | No versioning of the snippet itself, weak reporting |
| Includes and transclusion in a docs-as-code pipeline | Engineering-adjacent teams already using Git | Where-used tracking requires custom tooling |
| Structured authoring with a component repository | Multi-product, multi-language, regulated output | Significant setup cost and author retraining |
| Database-driven content assembly | Highly repetitive catalog or specification data | Poor fit for narrative or explanatory prose |
Typically, organizations that have considered translation as part of their content reuse end up at row 3. As most organizations quickly realize, re-translating strings that have been duplicated throughout the organization is cost-prohibitive. Teams weighing that move are best served by first reading up on what a CCMS is and how it differs from a document-oriented repository, designed to manage whole documents as opposed to individual topics that can be reused throughout an enterprise.
Handle variation without forking the source
Similar content, model numbers with slightly different characters, an additional step that only one audience needs, or silent forking of slightly different content, is the hardest content to handle for reuse.
Three techniques cover nearly all variation cases.
- Conditional profiling. Tag elements with attributes such as product, audience, or output format, then filter at publication time. Keep the attribute vocabulary short, ideally under ten values per dimension, or filtering logic becomes unreadable.
- Variables and key references. Replace product names, version numbers, and URLs with resolvable keys. Changing a product name across a thousand topics then becomes a single edit to a key map.
- Conref push and overrides. Where a reused block needs a local exception, use a mechanism that records the override explicitly rather than copying the block and editing it.
Set a threshold for when forking is acceptable
Conditional logic of even moderate complexity should not be relied upon to support a chunk that manages more than 3-4 dimensions of variation. Set such a rule and inform your authors.
Build the workflow around where-used visibility
Content reuse impacts content authoring and introduces new risks of unintended effects of even minor changes to published content.
Also, the where-used reporting for a piece of content should be available where the content is edited (e.g. In the same authoring application) and not hidden away in some administration tool. Your authors will behave differently if they can see that the topic they are writing is used in 11 places in 11 different manuals for 3 products.
- Assign an owner to every reusable component, not to every document.
- Require review from downstream document owners when a shared component changes materially.
- Version components independently so a deliverable can pin to an approved revision while others move forward.
- Report on reuse rate quarterly, and investigate topics with a reuse count of one, which usually indicate failed chunking.
Measure the return honestly
Translation savings are obvious and can be easily quantified. A topic used in 6 manuals in a documentation set is translated only once instead of 6 times for example.
Count the costs the business case usually omits
At first, authors will lose speed in the writing process in the first two quarters after a system has been introduced to them, as they have to search for already written content instead of starting from scratch. Subsequent review cycles for reused content will be longer, because all authors of a reused component have to sign off for changes to that reused component. Taxonomy for the re-used content has to be maintained over time, usually on an ongoing basis, not as a one-time project task. Organizations will sustain their reuse programs only if they have budgeted for these special needs of re-use; organizations treating re-use only as a one-time migration of content to a repository will find that their content corpus will return to duplicated versions of similar information within two release cycles.
