Content Reuse

Content Reuse - Write it Once, Use in Many Places

Overview

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

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.

Content Reuse - Write it Once in One Place

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.

Benefits of Content Reuse

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:

  • 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.

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).

Topic Reuse

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.

Content Reuse - Reusing Topics

'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 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.

Content Reuse - Reusing Snippets

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 - 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. These are great for things like product names, where you can set the value to a different product name, depending on which manual you are creating.

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.

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. Sorry, but I have to approve comments before they appear, otherwise I end up being bombarded with spam.

Craig Wright technical author

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.

Email help@straygoat.co.uk
Phone +44 07954141761

Straygoat Writing Services Ltd
26 Wheatlands Road
Wingerworth
Chesterfield
Derbyshire

Registered Number: 08029184

Straygoat logo design by Bristol graphic designer, Nik Jones.

© Straygoat Writing Services Ltd.