Craig Wright is an experienced technical writer based in Chesterfield, UK. He hates writing about himself in the third person, so I shall stop now.
Always interested in new content writing opportunities. Remote working preferred.
If you are a technical writer or work with 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 I've included navigation links below.Links to Other Sections
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.
Now that you know what content reuse is, let's look at how it can save you time, effort, and money.
Technical writers often have to create content in bulk. Rather than write one manual or create a help system for one product, we often have 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.
When used correctly, content reuse can:
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.
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).
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 approach means it is easy to reuse an entire topic in more than one user guide.
'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 a location 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.
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:
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:
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.
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:
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 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. Sorry, but I have to approve comments before they appear, otherwise I end up being bombarded with spam.
Craig Wright is an experienced technical writer based in Chesterfield, UK. He hates writing about himself in the third person, so I shall stop now.
Always interested in new content writing opportunities. Remote working preferred.
Registered Number: 08029184
Straygoat logo design by Bristol graphic designer, Nik Jones.
© Straygoat Writing Services Ltd.