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
Hi Sarah, this was very helpful information! I’ve been doing a lot of research and reading on using Confluence wiki the past few weeks as I’m migrating a bunch of internal pages from Twiki to Confluence. I was wondering about how to include content from other pages — along the line of single-sourcing within Confluence. I didn’t know about the {excerpt} or {excerpt-include} macro.
Can you assign a label or name to an excerpt? For example, if a page has 3 different “excerpts” that I want to reuse on another page, how do I make the distinction?
Also, does this InclusionsLibrary work on Confluence 2.6? Thanks!
Susan
19 July 2008 at 4:44 pm
Hallo Susan
Wow, that was quick! It seems to be just a few minutes since I posted
I’m really glad it is useful.
No, you can’t assign a label to an excerpt — there can be only one excerpt per page. There is an improvement request on JIRA somewhere asking for just this feature. But a big advantage of the “inclusions library” idea is that it gets around this shortcoming. You can make your bits quite modular in the inclusions library, so you only need one “excerpt” per page.
Yes, as far as I know you should be able to use the macros in Confluence 2.6. Here’s the documentation — I hope it helps
Fun getting your comment so quickly!
ffeathers
19 July 2008 at 4:56 pm
Great blog Sarah – keep up the great work!
Matt [Atlassian]
20 July 2008 at 9:19 pm
Very interesting article, and a very good feature in Confluence.
I’ve been experimenting with something like this in TWiki (the wiki used where I’m consulting right now). Unfortunately, TWiki’s abilities in this area definitely aren’t as advanced as those in Confluence.
How granular do you get in your re-use? Paragraph level? Section level?
Scott
21 July 2008 at 1:20 am
Hallo Scott
Thanks for your comment
The granularity of the pages in the inclusions library varies. Sometimes, like on this page, the content is very modular indeed. On that page, only the last paragraph is excerpted for inclusion onto other pages. We’ve done this to protect ourselves against UI changes — each time the menus change, the “how to” instructions on multiple pages are affected.
In other cases, like this page, there’s a lot of information which logically fits together. It seems likely that all the information will be needed each time we try to explain this concept. So on that page, everything is included in the excerpt except the “Related Topics” at the end of the page.
As a general guiding principle, I’d say keep the inclusions as short as possible because that’s the most flexible. You can then combine them easily. Whereas once the inclusion is defined and used, it’s much more difficult to break it into smaller pieces.
ffeathers
21 July 2008 at 7:59 am
[...] weekend, I was reading Sarah Maddox’s blog, and she mentioned how this is done in Confluence — a solution that’s a lot more elegant than the similar feature in the [...]
Reusing content on a wiki by Communications from DMN
24 July 2008 at 7:03 pm
Hi Sarah
Loved the pics of the possum ‘reusing’ the phone lines! And a great segue from the serious work-side of you into the personal. I think we have a family of possums (maybe they’re rats??) in or on our roof, who decided two days ago to reuse the insulation as their new nest…
Rhonda
13 August 2008 at 7:10 pm
Hallo Rhonda, great to hear from you
LOL. If they make an awful lot of noise, like a baby elephant trying to imitate a bird, then they’re possums
ffeathers
14 August 2008 at 8:14 am
[...] – bookmarked by 6 members originally found by lybrerian on 2008-08-19 Content re-use on a wiki http://ffeathers.wordpress.com/2008/07/19/content-re-use-on-a-wiki/ – bookmarked by 2 members [...]
Bookmarks about Wiki
11 September 2008 at 8:30 pm
Hi Sarah,
How many times are your sections or items generally reused before you determine they need to be put in the inclusions library? I’m wondering about the pro of standardizing text vs. the con of limiting collaboration on our Wiki. I can see the benefit of using the excerpt macro for standarizing definitions, for example, but generally, we don’t reuse an entire definition, we link to them instead.
Do you have any other tips or rules for getting started using the excerpt macros?
Thanks for the enlightening post! I know we’ll be able to use this function somewhere once I wrap my head around it a little better.
Rosemary
Rosemary
19 November 2008 at 8:51 am
Hallo Rosemary, That’s a good question. There are a number of factors involved in the decision to put something in the inclusions library. From the point of view of collaboration, it depends on the type of contributors to the wiki. Ours are mainly staff, so we can let them know about the function and use of included pages. We also put some hidden text at the top of such a page, explaining it’s function.
Linking to content instead is definitely a good option in many cases. I’d recommend using includes for small chunks that are used in more than two places and for those which are likely to need updating.
BTW, there’s an interesting discussion happening about the good and bad sides of content re-use in general. See Content Reuse: Is It Harmful? by Richard Hamilton on The Content Wranger, and the comments it has attracted.
ffeathers
21 November 2008 at 6:12 am
Hi there Sarah,
Back to your comment:
>We also put some hidden text at the top of such a >page, explaining it’s function.
Could you point us to a page containing such hidden text? I’d like to test your approach of managing content in my organisation…
Thanks!
Stéphane.
KalpaK
28 December 2008 at 2:16 am
Hallo Stéphane
Here’s an example of a page using hidden text at the top of the page:
http://confluence.atlassian.com/display/CROWD/_About+Crowd.
To see the hidden text, click “Tools” and then “View Wiki Markup”.
You’ll see that we have used a macro called “{hide}”. This is actually a user macro, which you can add to your own Confluence site. There are instructions for adding a user macro here:
http://confluence.atlassian.com/display/DOC/User+Macros
Basically, create the “{hide}” macro with options:
Name = “hide” (or whatever you want to call it)
Has a body = yes
Use Unprocessed Macro Body
Macro Generates HTML Markup
Template = “<!–$body–>” (without the quotes, and those are two sets of two double hyphens not an n-dash)
You can also try the {html-comment} macro, if that is enabled on your Confluence site.
I hope this helps. Have fun
Sarah
ffeathers
28 December 2008 at 6:54 am
[...] (to a limited extent) on a wiki. I discussed this in a previous post, and Sarah Maddox looked at how do this in [...]
The medium is the delivery method by Communications from DMN
7 April 2009 at 7:01 pm