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

Content re-use on a wiki

Content re-use on a wiki

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 19 July 2008, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , , . Bookmark the permalink. 27 Comments.

  1. 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!

  2. 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!

  3. Matt [Atlassian]

    Great blog Sarah – keep up the great work!

  4. 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?

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

  6. 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…

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

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

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

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

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

  12. Thanks for the pointers. Mindtouch has a fairly sophisticated inclusion feature (they call it transclusion) based on rpath queries. They can do this because all content is in XML, so any section with an ID, be it a DIV or SPAN or paragraph can be included easily.

  13. Hallo Peter
    That’s really interesting. Your comment prompted me to Google Mindtouch XML. The searched picked up this interesting blog post about XHTML and Mindtouch Deki. It lists some of the other advantages of XML over wiki markup, though it doesn’t mention the transclusion. Thank you for the great information!
    Cheers, Sarah

  14. Hi Sarah,

    check out this posting on the forum which deals with transclusion – http://forums.developer.mindtouch.com/showthread.php?t=4301&highlight=transclusion

    — Peter

    • Ah thanks Peter! So, the transclusion side of things is not very easy for non-technical authors then :)

      I found the discussion of XML vs wiki markup very interesting, and also interesting to read about a wiki that has gone the XML path. Confluence, our wiki, stores content in wiki markup. The topic of converting to XHTML comes up regularly, resulting in heated debate about whether it would be a Good Thing or not.

      Heh, fun.
      Cheers
      Sarah

  15. The arguments in favor of XML line in the ‘X’ factor – it’s extensible in a way that everybody understands. It’s also standardized, and we have ubiquitous libraries for parsing, transforming and generating XML. It’s also consistent with the XHTML.

    While rpath queries can be hard, they also have a power that is absent from other inclusion systems. For example, an rpath query can return all DIVs of a given class, enabling you to build the one-page encapsulation of a manual without knowing the explicit names of all the sections in the child pages.

    As someone who like to writes code to inject content into wikis I find XML extremely convenient. On the other hand, finding useful libraries for producing, parsing or querying wiki markup (of any flavor) for C#, VBA, Python, ECMAscript, PowerShell, etc. is a thankless task.

    A lot of the facility of Mindtouch also comes from the integrated DekiScript which allows manipulation of XML and the REST interfaces which are easy to deal with from other languages, especially scripting languages.

  16. I have started using the include macro to include pages which are re-used across more than one of our products. However, it’s difficult to know what to do about links within the re-usable pages. They need to link to other pages within the current product space with a specific name, but in fact they link to pages in the original space with that name. I have no idea of how to get around this.

    • Hallo Felicity
      Good point! We usually avoid links in the reusable chunks. Instead, we put them at the end of the page where the chunks are used, in a section called “Related Topics”. Sometimes we put a “for more information” link at the end of each section, after the inclusion, or at the top of the page.

      This is a common, and much discussed, topic in the world of content reuse. It’s relevant whether you’re using a wiki or another tool such as DITA. People often talk about it as “context” — whether your chunks should or should not include context-specific information.
      Cheers
      Sarah

  17. Hallo all :)
    I’ve written a new post that you may find useful. It’s a case study of a new set of documentation designed specifically for content reuse:

    http://ffeathers.wordpress.com/2011/04/03/content-reuse-on-a-wiki-a-case-study/

    Cheers, Sarah

  18. Hi,

    I’ve been following your website off and on and this topic is quite interesting to me. I have used transclusion (content re-use) in Twiki and MediaWiki. Twiki was far easier and supported one thing that I haven’t seen mentioned which is cross-wiki transclusion. Often inside organizations various groups use different wikis (an entirely different problem). I have used cross-wiki transclusion to prevent the recreation of the same information in multiple wikis (a big waste of time). Right now I was searching to see if Confluence supported cross-wiki transclusion. There are a number of other interesting workflow tricks that transclusion provides to the technical writer but that’s another topic.

    • Hallo Cheryl

      Confluence doesn’t support transclusion across wikis. It’s an idea I’ve been tossing around too! I didn’t know that Twiki could do it.

      What you can do with Confluence is use a “page gadget” to display the content of one page on another site. But that’s not the same as transclusion.

      Have you seen the work that Ward Cunningham is doing with federated wikis? Very cool: http://c2.com/cgi/wiki?FederatedWiki

      Thanks for a nice comment. :)
      Cheers, Sarah

  1. Pingback:   Reusing content on a wiki by Communications from DMN

  2. Pingback: Bookmarks about Wiki

  3. Pingback:   The medium is the delivery method by Communications from DMN

  4. Pingback: More about content re-use on a wiki « ffeathers — a technical writer’s blog

  5. Pingback: Content reuse on a wiki – a case study « ffeathers — a technical writer’s blog

  6. Pingback: The “One Thing, in One Place, Once” Rule using Confluence « JodieM.com.au

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,472 other followers

%d bloggers like this: