Content re-use on a wiki

You’re writing a page on a wiki and you realise that some words you wrote just the other day would make sense here too. But where oh where are they? Or you want to include a picture, such as a logo, that’s used on other pages all over the show. Of course, you could just copy and paste. But can the wiki be more sophisticated than that?

I use the Confluence wiki for technical documentation. Some parts of this blog post are very specific to Confluence, because I thought other Confluence fans might find them useful.

For people who aren’t using Confluence, the first bit and the last bit of this blog post are for you 😉 The basic idea is that wikis (at least some of them) do allow content re-use. And the question at the end is, do you have any experience or hints about other wikis?

A quick note on terminology: In this blog post I’m using the words “content re-use” to mean the re-use of text or pages within the wiki itself. I’m not referring to single-sourcing of content across multiple media.

Why re-use content?

It saves time if you don’t have to keep re-inventing the word 😉

Another problem with duplicated content is when something changes. You could easily miss some of the pages that need updating. So you run the risk of contradiction, incompleteness, and content which is just plain wrong.

If you want to translate your documentation into another language, it’s a great advantage to have as few words as possible. If you plan to engage someone else to do the translation for you, they will probably charge by word count or page count, so it could save you some $$ too.

Including content from other pages in Confluence

Confluence allows you to dynamically include content from one page into another page. You can include a whole page into another one, using the {include} macro. You can also define an ‘excerpt’ on a page, and then include that excerpted text into another page using the {excerpt-include} macro.

That’s old hat. We’ve been doing that for years 🙂 So why am I writing about it?

Because we’ve started doing things a bit differently recently, and I thought other people might like to know about it.

At first, we did things like this:

• We defined an excerpt on the first page that happened to contain the wording we wanted. Then we included that wording into other pages as needed.
• Or we included an entire page from anywhere in the wiki into another page in the wiki.

There are a few disadvantages to doing it that way:

• When a whole page is included in another page, there’s no indication that the content is being re-used elsewhere. So anyone might change or even delete the page without realising they are affecting other pages.
• For both partial and whole includes, anyone might change a page name without realising that they are breaking the {excerpt-include} and {include} macros. (Confluence does not automatically fix changed page names in macros, only in links.)
• Re-used content is scattered throughout the wiki.

The better way

Now we’re using a set of pages called an “inclusions library”.

Here are some examples in our documentation:
Crowd Inclusions Library
Confluence Inclusions Library

Some notes about the inclusions libraries:

• The pages are located at the root of the wiki space, not under the “Home” page. This means that they will not appear in the table of contents on the left and they will not be picked up by the search in the left-hand navigation bar either.
• The pages will be picked up by other searches, because they are just normal wiki pages.
• For all new pages, we have decided to start the page name with an underscore e.g. “_My Page Name”. This indicates that the page is slightly unusual, and will help prevent people from changing the page name.

Including images from a central image repository in Confluence

You can attach your images to a single page and then include them into other pages. This means that the images are in one central place, instead of attached to an unknown number of pages. Here’s an example of an icon repository in our Atlassian IDE Plugin documentation.

What about you?

I did a very quick search to see what other wikis offer. The Socialtext documentation says you can include the contents of a page into another page. So does TWiki. That’s as far as I got.

I find this sort of feature offering really interesting because it shows that wiki creators are designing features for technical documentation and other formal writing, as much as the less structured collaboration use that is the wiki’s traditional comfort zone.

Have you used any content re-use features as part of the design of your documentation system, or are you using a wiki in this sort of structured way?

Re-use of a different kind

Here’s a ring-tailed possum making use of our telephone lines as a handy path from A to B.

Content re-use on a wiki

Content re-use on a wiki