Content Reuse — The art of not writing the same shit over and over again!
If you are a technical writer or hire technical writers, you may have heard of the term “content reuse”. In this article, I’m going to explain what it is, what benefits it provides, and what you need to think about when using content reuse.
It’s quite a long post, so brace yourself.
What is Content Reuse?
Content reuse is a way of using the same (or similar) pieces of content in several places. It allows us technical writers to create ‘common’ pieces of information once, in one place. The ‘common’ content can then be embedded in lots of different documents or topics. This means that when content needs to be updated, it can be changed in one place and that change will apply automatically wherever that content is used.
For example, let’s say you have user guides for a range of three cameras. The cameras have some features that are common to all three models. Instead of writing the content for the ‘common’ features three times, I would write them once and then use that same set of content for all three versions of the user guide.
And if content is mostly the same, but not identical, there are usually condition features to allow for alterations. For example, you can add a paragraph that is shown in one version of the user guide but not in another.
But content reuse doesn’t have to be limited to ‘common’ content. With structured writing, every piece of content can be designed for reuse.
Now that you know what content reuse is, let’s look at how it can save you time, effort, and money.
Benefits of Content Reuse
Technical writers often have to create content in bulk. Rather than write one manual or help system for one product, we often need to create content for a range of similar products. This can be time-consuming and costly, so anything that speeds up the process and makes it easier is always welcome. That’s what content reuse does.
Content reuse lets writers create content once, in one place and then add it to lots of different publications. It means we can build manuals quickly from existing chunks of information. And when we need to make updates, we don’t have to repeat the update work in every version of a manual/help page. It’s one change, in one place.
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.
- Help you to avoid duplicating work.
- Help you to avoid extensive copying and pasting (where mistakes often happen).
To take advantage, you need an authoring tool that has content reuse features. My favourite tools are Paligo and Flare, and both have powerful content reuse capabilities. They handle it differently, as Flare is file-based, whereas Paligo uses a database (which gives it extra versatility). It’s even possible to have content reuse in Word, as there is a SmartDocs solution for that. But a lot of the CMSs and wiki tools use simple editors and don’t have content reuse or conditional content capabilities (at the time of writing).
Types of Content Reuse
There are two different types of content reuse, which I think of as ‘topic reuse’ and ‘snippet reuse’. I’m going to explain both, so that you can see how they could make it easier to write and update your documentation. (I’m using the term ‘snippet’ here instead of ‘chunk’, but they mean the same thing).
Note: The types of content reuse are not mutually exclusive.
Topic Reuse
Many modern technical authoring tools use a topic-based approach, which means that the content is written in lots of individual chunks (topics) rather than one big file.
If you’re used to writing in Word, you’ll have an entire document in one file. With topic-based writing, that same document would be made up of lots of different topics (which could be individual files or database entries). So you might have a ‘Charge the camera’ page in a Word document that could be a single topic file. It’s also possible that the ‘Charge the camera’ page could be made up of several topics, for example, one topic for the introduction (concept), one for the ‘how to’ information (task), and one for extra information (references). Different tools/standards approach the use of topics in different ways.
The key thing with topics is that they should only cover one subject. So you might have a topic for ‘Charge the camera’ but you would have a different topic for ‘Turn the camera on/off’. This focus on a single subject is important, as if you have topics covering multiple things, they become much harder to reuse.
‘Snippet’ Reuse
‘Common’ information doesn’t always fit into nice, topic-sized packages. Sometimes, you need 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 smaller pieces of reusable information. In Flare, they are ‘snippets’. Paligo and other tools use different terminology, but the basic principle is the same.
The idea is that you create your reusable content in a separate location (the snippet) to your actual content. The snippet could be a file or an entry in a database.
You then embed the snippet in the topics that need it. For example, in Flare, I often create the individual steps of procedures as snippets, as steps tend to be repeated in lots of different procedures. When I’m writing a procedure, I can then embed the ‘common’ steps into place, rather than having to write them separately each time. I wrote an article about this over on the MadCap site, see:
https://www.madcapsoftware.com/blog/2018/04/05/make-the-most-global-project-linking-madcap-flare/
In the image below, you can see how ‘snippets’ of information can be written separately to topics, and then inserted into the topics as and when needed.
What If Content Needs to be Similar, but Not Identical?
When you have a set of user guides for similar products, it’s likely that they will have some content that is similar but not exactly the same. For example, you might have introductions that are the same except that the product name is different in each user guide. Authoring tools often have features for handling this, and the two most common are:
- Conditional Text /Content Filters— With conditional text, you can mark content to be included or excluded from your finished publication. This is useful when you need different variants of content, such as different images for different products.
- Variables — Variables allow you to set values for text. So instead of adding regular text, you insert a variable, which is like a text field that has its value defined elsewhere (in a variable list). For example, you might add a variable called ‘product name’ and then in the variable list set the product name value to ‘Camera A’. In another publication, you might change the product name value to ‘Camera B’.
Conditional text gives us a quick way to show/hide content for different publications. Variables give us a quick way to change small pieces of content, such as names and dates, for different publications.
Is there a Downside to Content Reuse?
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 disorganised. 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. It often requires compromises too, which is something that some writers, including myself at times, are uncomfortable with. As reusable content could be embedded in lots of different topics, it is important that it is always used in the right context. This may mean that the content needs to be a bit more generic than you’d normally write. It also means that 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.
Content Reuse Strategy
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 try to stick to it as much as possible.
Reusable content needs to be planned, written, and organised so that it:
- Is easy for your writers to find.
- Is generic enough to be used in different topics, but contains all the details that an end user needs. If it doesn’t meet those needs, it is of no use.
- Only includes links to content that is definitely going to be included in the output that the end user sees.
- Is consistent. Try to stick to a ‘write the content once, in one place’ approach.
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.
In the authoring environment (i.e where the writers work with the content), it is best to organise the content by its meaning. This is often called domain modelling. So you will have all of the topics about one subject in one place, and therefore easier (in theory) to find. In reality, it can be difficult to achieve, as different writers may have different perceptions of what is or isn’t included in a subject. That’s one of the reasons I like Paligo as a tool -it lets you apply taxonomy tags to topics, so you can view content by whatever tag it has as well as by name/folder.
For the publication, you might need a different structure completely. Here, you need to think more about how end users are going to find content. So you’ll probably have some form of content modelling for the main navigation structure. Using our camera example again, you might have a structure that has each camera model at the top level, and then the sub-levels are organised by subject matter (domain model).
Over to You
I hope this post has helped explain the concept of content reuse and given you an idea of how to use it on your projects. As usual, if you have points to add, think I’m talking a load of old cobblers, or have questions, let me know in the comments and I’ll get back to you.
If you get stuck, you could try hiring a technical writer … there are freelancers out there willing to help (like me!).
Thanks for reading. I’m Craig Wright, a freelance technical writer in Chesterfield, UK. I help businesses by explaining how their products and services work, in terms their customers understand.
