How to reuse content in Atlassian Confluence with Scroll Versions

K15t Company

Published on December 5, 2019 in

misc

3 minutes read

Software developers and technical writers have different roles and no doubt work in different ways. But they have one thing in common: they hate doing anything more than once. So both groups are naturally very interested in the concept of reusability, also known as the DRY principle ("don't repeat yourself").

Everyone on our team, whatever their job, just loves the idea of reusing content to eliminate unnecessary work. We’re all extremely busy people, after all.

Confluence already offers features that let you include pages or excerpts of a page, which you can use to introduce a content reuse strategy.

Scroll Versions introduces some additional features on top of this:

Support version and variant management
Highlight included content
Display additional include information

So let's take a look at the main principles of content reuse, and how content in Atlassian Confluence can be reused with Scroll Versions.

What's in it for me?

Beside the obvious advantage of avoiding duplication of effort, does reusing content offer any other benefits?

By increasing consistency, content reuse improves the quality of your content: Identical information appears in the same form everywhere in your document. That saves you time when you’re writing and editing – changes only have to be made in one place and then take effect everywhere. And importantly, it helps your readers to understand your product better. Imagine, for instance, how frustrating it would be to encounter different instructions for the same task – with no way of telling which is correct.

In practice, there are some potential pitfalls you should be aware of. So – in the words of Pink Floyd – let's look at the dark side of the moon and consider the challenges involved in reusing content.

Reusing content – the challenges

The scenarios in which content is typically reused are more or less complex. In centralized teams with only a few authors, for instance, content reuse can be very useful and brings a host of benefits. In very large, distributed teams, conversely, it can be difficult to manage reuse correctly, and the disadvantages can even outweigh the advantages. The recipe for success is careful planning before you start reusing content throughout your docs.

When you want to reuse content in Atlassian Confluence, the product’s simplicity is both a disadvantage and an advantage:

On the one hand, it doesn’t offer much functionality for using a taxonomy or working with metadata. (You could work with labels, of course, but that soon reaches its limits).
On the other hand, simplicity has its advantages, as you can use the parent/child page structure to organize your snippets. When done properly, this increases clarity.

Another challenge is finding the right balance between too much content reuse and too little. It’s a question of complexity: the need to keep your content reuse strategy manageable.

Pages that consist of multiple includes are harder to edit. Instead of editing a single page, you may need to rework five pages that are included elsewhere, and afterwards check whether the repeated content makes sense on every page it occurs.

That's why you should use only plain text and keep your reused snippets as small as possible. The smaller your snippets, the greater their reusability. If a snippet contains multiple paragraphs with several headings, reusing it can be less straightforward: the headings may not match every page structure and so can't be reused everywhere as-is. The content needs to match the context on each and every page.

Finally, all authors must always be able to see where chunks of content are duplicated. There’s only a thin line between simplification and excessive effort.

Plan your reuse strategy carefully

As I already mentioned, careful planning is vital when reusing content. Here are four simple rules:

Don't overdo it: make sure your expectations are reasonable. Content reuse can reduce your workload, but it can also make things more complicated. Remember to keep your snippets as short as possible.
Check your existing content carefully to identify exactly where duplicating content really does make sense.
Implement content reuse in phases: first identify the area likely to benefit most, implement it there, and become familiar with the reuse method before spreading it to other areas.
I recommend taking small steps to get used to the concept and avoid overtaxing your authors.

Let's get practical – content reuse in Atlassian Confluence with Scroll Versions

After all that theory, it’s time to get practical and look at how content in Confluence is reused with Scroll Versions.

There are only two steps required to reuse content with Scroll Versions

Create an inclusions library
Define your include settings

The following screencast will demonstrate these steps in detail.

Why do I have to use the Includeplus Macro?

Why, you might ask, have we developed a special macro for functionality that’s already implemented in Confluence? We did it for a simple reason: it works like a charm with the core functionality of Scroll Versions. It lets you have multiple versions and variants in the same space. Besides, the macro offers additional features, as I explained in the screencast:

Highlighting included content – to see which paragraphs have been included from other pages.
Showing include information – to see which pages are affected by changes.

What’s your experience with reusing content? Are you already using Scroll Versions and benefiting from its enhanced content reuse functionality?

Share this article ✕