More about content re-use on a wiki

Saturday, 31 July 2010 02:19

A while ago I wrote a post about content re-use on a wiki. Just recently I’ve discovered that the ??? macro has a handy parameter: “hidden=true”. So I thought I’d tell you about it.

In Confluence wiki, you can dynamically include content from one page into another page. These are the macros to use:

Use the ??? macro to include a whole page into another page.
Use the ??? macro to define a re-usable chunk of text (an ‘excerpt’) that is part of a page, then include that excerpted text into another page using the {excerpt-include} macro.

My recent “eureka” moment happened when I noticed the “hidden” parameter in the ??? macro:

{excerpt:hidden=true}Blah blah blah.???

If you specify “hidden=true”, the content between the ??? tags will not be displayed on the page where the excerpt is defined. It will, however, be displayed on the page where the excerpt is used via the {excerpt-include} macro. Magic!

Here’s an example of a page that does just that. It’s from our SharePoint Connector documentation: _Access Confluence using IWA with IIS

I’ve added some text to the page, explaining that the content is hidden and telling people how they can see it if they really want to. Here’s a screenshot of the same page (click the image to expand it):

Why on earth would you want to hide the content of an excerpt?

It stems from the way we are using content re-use in our structured technical documentation. My earlier post goes into it in detail. Here’s a quick summary.

We create a special “area” of the wiki, which we call the “inclusions library”. It’s not really anything special. It’s just a set of pages that hold the chunks of content (text, images, etc) that we will use more than once, on various wiki pages. We also use an underscore at the start of the page names, to remind us that the pages are special. This helps to prevent us and other authors from editing the included content by mistake.

The thing about a wiki, though, is that people may stumble across the pages in our “inclusions library”. They may wander in via Google search, and not realise that this page is just part of a set of instructions. Sure, it’s got a weird page name. But hey, it’s a wiki. What do you expect?

It may even be a bit traumatic for them if they start following the instructions, without having performed the preceding steps.

Here’s one of the pages that use the excerpt from the above page. This page is neatly in place in the full installation sequence: Access Confluence using Integrated Windows Authentication via IIS with SP 2010. Much less chance of our poor Googler going off the beaten track.

I think the “hidden=true” parameter is pretty neat. I don’t know why I didn’t notice it before. Now you know about it too!