Reducing your Documentation Costs with Content Reuse
What is Content Reuse and How Can it Save You Money?
Content reuse is a way of using the same pieces of content in several places. It allows you to create 'common' pieces of information once, in one place, and then they can be shared between different documents or topics.
When used correctly, content reuse can:
- Speed up the document creation process.
- Make it easier and quicker to update your documentation.
- Make your documents more consistent, especially if lots of writers work on the same project.
- Reduce the amount of duplicated work.
- Remove the need for extensive copying and pasting (where mistakes often happen).
Content reuse saves time, effort, and money, so it is definitely worth knowing about. On this page, I'm going to explain the basic concepts, so that you can see the benefits it can bring. I'll also cover some of the pitfalls, because content reuse isn't for everyone - it takes a bit of know-how to make the most of it. If you're new to the idea of content reuse, the following information should help.
Why Repeat Content?
If you look closely at technical manuals and online help systems, you'll see that there is a lot of repetition. Now, it may not be whole pages that are repeated, or even whole paragraphs, but there will be text that appears over and over again. The most common example is in software documentation, where you will often see steps like 'Click on the Save button.' and 'Select File > Open.' repeated in many different procedures. The repetition is needed, because it is information the user needs to know, and it is bad practice to expect them to navigate between lots of different pages to complete a single task. But that doesn't mean that your writer should be writing the same text in multiple places. With content reuse, 'common' content should exist once, in one place, so that it can be shared wherever it is needed.
There are different types of content reuse, which I'll explain next.
Types of Content Reuse
There are two different types of content reuse, which I call 'topic reuse' and 'section reuse'. I'm going to explain both, so that you can see how they could make it easier to write and update your documentation.
Many modern technical authoring tools use a topic-based approach, which means that the content is written in lots of individual files (topics) rather than one big file. This modular approach means it is easy to reuse an entire topic in more than one user guide.
For example, let's say you have two hardware products that are physically identical, but they have different firmware and functionality. The topics that cover the physical aspects of the products are going to be identical (except maybe for the product name), so rather than write the same topics twice, I would write one set of topics that could be used in both user guides. To handle the different names, I would use a variable (we'll come to those later). So we have two products, two user guides, one set of topics for the common content, and two other sets of topics for the firmware content.
With topic reuse, it is really easy to build documents from similar, existing content. And if little bits of the content need to be changed, there are often features for handling that too.
Of course, 'common' information doesn't always fit into nice, topic-sized packages. Sometimes, you need lots of topics to share a smaller amount of information, such as a simple explanation, an example, or a step in a process. Can it be done? Of course. Lots of technical authoring tools have features for creating chunks of information that exist separately to your topics, but can be embedded in them. The chunks of information are often called snippets, but different products use different terms (but the principle usually the same).
The basic principle of reusing sections is that you create your reusable snippet, and then you include it in the topics that need it. For example, I often create the individual steps of procedures as snippets, as steps tend to be repeated in lots of different procedures, especially with software. When I'm writing a procedure, I can then drag and drop the 'common' steps into place, rather than having to write them separately each time.
In the image below, you can see how 'chunks' of information can be written separately to topics, and then inserted into the topics as and when needed. For the image, I've used steps in processes as snippets, and also a longer explanation of a common concept.
What About When You Need to Reuse Content, but with Slight Differences?
It's likely that at some point, you will want to reuse a section that already exists, but you'll need it to be slightly different. For example, you might need an introduction to be the same, but with a different product name, or you might need an explanation but with an added couple of lines in the middle of the text. Do you need to write fresh content to achieve this? No, of course not. Many technical writing tools have features that allow you to change parts of the content, and the two most commonly used ones are:
- Conditional Text - With conditional text, you can add markers to a piece of text. Then, when you come to publish the documentation, you can set it to include or exclude text that has those markers. This is really useful when you have content that needs to be excluded for some outputs. For example, you might have a paragraph that doesn't apply to a certain model of your product.
- Variables - Variables allow you to set certain terms to use a value instead of text. When the documentation is built, you enter the value that should be used, and it is applied wherever that variable appears.Variables are great for things like product names, as you can use a generic 'product name' variable throughout your content, and then when it comes to publishing, just enter the name of the product once. Then, if you use the same content in another manual, you can just change the value of the product name variable again.
Different products use different terms for conditional text and variables, but if there are content reuse features available, there is usually some form of conditional text and variables too. If you're going to take advantage of content reuse, you really do need to learn how to use conditional text and variables, as they make your reusable chunks more flexible.
Is there a Downside to Content Reuse?
I'm a big advocate of content reuse, but then I would be, because I'm a technical writer. For people who aren't technical writers, content reuse can quickly become frustrating and confusing, especially if there isn't a clear reuse strategy in place. So when I'm working on a new project, one of the things I always ask is: who will be contributing to the content? Because if you have a hands-on team, where people will be expected to add to the content themselves, there is a decision that needs to be made - are they going to be trained to use content reuse features, or should content reuse be avoided from the start? I've found that software engineers 'get it' very easily, whereas people with different skills sometimes struggle.
The most common problems I see are:
- People changing reused content to suit their purposes, without considering the other places where that content may appear.
- There being no clear content reuse strategy in place, so the whole thing is a mess. If people can't find the reusable content, they will recreate it, which goes against the whole purpose of content reuse.
- People including links in the reusable content. It's fine to include links if you are certain that the target of the link will always be included in the finished document, but that's not always the case.
It takes some writing skill to create reusable snippets that will work in lots of different topics. Quite often, the content needs to be slightly more generic than you'd normally write, and the writer needs to have an appreciation of how the documentation works as a whole, so that they know the impact of any changes they make.
Planning for Content Reuse
In the wrong hands, content reuse can get really messy, really quickly. I've implemented content reuse plans on several projects now, and from experience, I can say that it is really important to make a plan at the start and stick to it as much as possible. The more you deviate from the original plan, the more likely you are to cause confusion further down the line. Even if technical authors are the only people who will contribute to your documentation, the reusable content still needs to be planned, written, and organised so that it:
- Is easy to find
- Is generic enough to be used in different topics, but contains all the details that an end user needs
- Only includes links to content that is 100% definitely going to be included in any project that uses the reusable 'chunk'
- Is consistent.
Every project is different, so there's no clear-cut right and wrong way of planning for content reuse. But on the projects I've worked on, there are definitely some patterns in terms of what content is set for reuse and what is standalone, regular content. I've found that on more complicated projects, adopting a DITA-esque approach of concept, task, references, example, can help too, although this can be a bit crude at times.