The “One Thing, in One Place, Once” Rule using Confluence

As a database designer, I am a huge believer in the “One Thing, in One Place, Once” rule (aka Normalization, in database speak).

As I’m currently building a full enterprise help system in Confluence, of course I’m going to extend that rule to my help content also.

I started with the ideas of Re-Using Content in Confluence and Building an Inclusions Library as written by Sarah Maddox from Atlassian, then as I started to need more features, I moved on to some of the other methods for content re-use, so I thought I would summarise them.

There are 4 ways that I use to re-use Content. The {include} macro, {excerpt} macro, the {multi-excerpt} macro and the {builder-show} macro. The {include} macro is the simplest and the {builder-show} is the most complex and most powerful.

I’m mainly using these features to produce a printable version of the help content, which is a bit different than the Wiki content, as it is presented in a linear fashion, and doesn’t have as many links to content unrelated to the narrative of the document.

Have a look at the following diagram, it shows some examples of the 4 macros that I regularly use. The first box is the base page, where the content is originally created. The second box is the wiki markup mode of the page where the content is included. The third box is what will show in the final layout of the page.

(click to enlarge)

Include Macro

The {include} macro simply includes the full content of the base page into the display page.

I use this macro for small notes and info panels that are used in multiple places.

On the display page enter the following in wiki markup mode:

{include:Base Page}

The {include} Macro is a bit limiting as most of my main pages has a section at the top that shows how you navigate to this screen – I don’t need that in my printed document.

The {include} Macro can be used from other spaces with the following syntax {include:SPACEKEY:Page name}. (Also see the Perimeter Plugin from CustomWare for the {secure-include} macro, which is useful for including from spaces that the user does not have access to).

Excerpt Macro

The {excerpt} macro allows for a defined section of the base page to be included in the display page. The content that is between the two {excerpt} tags can be included in the display page.

On the display page enter the following in wiki markup mode:

{excerpt-include:Base Page|nopanel=true}

I use this macro only occasionally for very simple pages as I find it a bit limiting as it can only be used for one continuous section of content.

The {excerpt-include} macro can only be used for content within the same space, similar to the {include} macro.

Multi Excerpt Macro

The {multi-excerpt} macro is part of the Multi-Excerpt Plugin. This is a very cool plugin, but it does cost – luckily it’s not that expensive.

This plugin allows you to have multiple excerpt sections in the base page appear in the display page – the cool thing is that the excerpts can be displayed in any order you want.

Each excerpt defined must have a unique name on the page.

On the display page enter the following in wiki markup mode:

{multi-excerpt-include:pageTitle=Base Page|name=excerpt1|nopanel=true}

The addition of the spacekey parameter allows the Multi-Excerpt macro to be used across spaces, so it is quite useful.

I use this quite a bit, but it still has one limitation – you can’t nest multi-excerpt macros – but I may be asking for a bit much there.

I use it to include the overall page description, then the screen shot, then the steps on how to use the screen, but exclude the navigation and the links to other pages, in my printed content.

Builder-Show Macro

The {builder-show} macro is part of the Adaptavist Theme Builder Plugin and is the coolest macro. The way I use it basically turns Confluence into a bit of database – yes it’s a bit complex to set up, but once it’s set up, the maintenance of the pages is going to be very easy.

Here’s how I use it – There are a number of fields on each screen. The same field can be used in multiple screens, and the same description is applicable to each screen. If I keep the description in one page, then I can use that description in multiple pages – but it only ever needs to be updated in the once place in future.

With the same field description being used on a few screen pages, and the printed manual for those screen pages, it can be used in up to 5 places – all based on the same source.

The main set-up for this macro is done on the base page, where we put in codes to say which pages the content will display on.

{builder-show:title=Display Page}
This is the first excerpt from my page
{builder-show}
{builder-show:title=Base Page}
This is the rest of my page
{builder-show}
{builder-show:title=Base Page, Display Page}
This is the second excerpt from my page
{builder-show}

The first and third sentences will be shown on the display page, and the second and third sentences will be shown on the base page. Sentence 3 will be show on both pages.

The display page contains the one macro – the {import} macro.

{import:Base Page}

And that’s all there is to it :).

There is one small limitation with this macro – the content on the display page must be shown in the same order as it is on the base page.

I hope that has helped give you some ideas on how to re-use content in your Confluence site, and if you have any more cool macros to share, please leave a comment.