Get hands-on training for JIRA Software, Confluence, and more at Atlassian Summit Europe. Register now ›

Revolutionise Your Confluence Space!

In Part 1 of of this series of blogs I explained how Confluence was used to revolutionise the Evaluator Resources space.
But how could you start using Confluence to organise and present spaces with lots of information so much more effectively? In this instalment of the series I’ll detail the steps we went through in designing the structure of the space.

Firstly, we used an inclusions library along with a couple of bundled macros to avoid duplication of content and improve visibility of information. Further, utilising CustomWare’s free Composition Plugin we created a set of tabbed pages that visitors new to wikis can resonate with.

1. What is is an inclusions library and why would I want one?

I originally learnt about the concept of an inclusions library after reading Sarah’s blog in which she mentions:

Looking closer, you’ll see that some of the information
is shown in more than one place. Using a wiki as our document
repository, how do we do that without duplicating the
text?…Confluence allows you to include content dynamically from one
page into another page

An inclusions library sits at the root level of your Confluence space and contains a bunch of child pages
each with re-usable chunks of information that you may use across
multiple pages in a single space or across different spaces. Sarah
explains it nicely here and I’ve added a screenshot below to give you an idea:


Take the blue buttons in the left hand column of every page as an example:

As this set of buttons is duplicated across all child pages in the Confluence Evaluator Resources, rather than attaching the images used for buttons to each page and duplicating the wiki markup required to create the linked images on each page, I added a single page in the inclusions library. This page is then included in any new child page created in the Confluence Evaluator Resources using the Include Page Macro:

IncludeButtons.jpgThe reason for the underscore and lack of spaces in the title of the
included page is purely to prevent it from showing up in any search
results that may be performed by a visitor.

HOT TIP: You can streamline the creation of new pages by creating a Confluence template and using CustomWare’s free Linking Plugin to create a new page using that template by clicking on a link

We also use the Include Page Macro when documenting the the answers asked in our Confluence webinars (as described in Part 1 of this series of blogs). Quite often we are asked questions for which the answers can already be found in our Confluence Documentation.
Rather than rewriting an answer which leads to duplicated information
and effort, we simply include the page from the Confluence
Documentation in our webinar questions and answers page.

2. What if I don’t want to include a whole page?

No problem, just use the Excerpt Include Macro. There are some cases where you may not want to include the entire contents of a page in another page. Take this page from the Confluence Implementation FAQ’s titled, How many versions of Confluence are there? as an example. This page is simply including an excerpt from the original Confluence Options page which is also used in a couple of other places in the space, including the landing page for people who have just attended a Confluence Webinar.

Why didn’t I just include the whole page? Well, the original page
also has the Confluence Buttons page included in its left column as do
the FAQ and webinar landing pages. If I were to include the whole page,
both the FAQ and webinar landing pages would have two sets of
Confluence buttons. So, I defined a section of the original Confluence Options page as an excerpt:


Then, I included the excerpt in the FAQ and webinar landing pages:

ExcerptInclude.jpgNote: Notice the nopanel parameter that I’ve set to true.
By default this parameter is set to false and as a result your excerpt
is embedded in a panel. This can be useful if you have a page acting as
a summary page that includes excerpts from a number of other pages.

HOT TIP: Include multiple excerpts from a single page across multiple spaces using the Multi-Excerpt Plugin

3. Why would you want the same information in more than one place?

Increased exposure. Having the same content in more than one place
increases the chance of that information being found. Using page
includes and excerpt includes we can present the same content with a
different page title or labels to increase its chance of being
discovered by evaluators. Best of all, if we want update the content of
that page in all the places it is displayed, we just have to edit the
original. We don’t need to worry about different versions of that
content in different places.

4. What’s with the tabbed pages?

My goal with the Confluence Evaluator Resources space was to differentiate it from the Confluence Documentation. I wanted it to have more of a website feel which I felt was less intimidating for evaluators that were new to wikis.


I didn’t want visitors to see a whole bunch of child pages when
viewing a parent page, so I leveraged the inclusions library and
CustomWare’s free Composition Plugin
to create tabbed pages. This allowed me to have a single page with
content that would normally be added as child pages as tabs on the one
page. Take the Confluence Videos page as an example:

ConfluenceVideos.jpgEach of the four sections of videos (Overview, Customer Implementation, Plugin of the Month, Other Plugin and Integration) have their own page in the inclusions library :

VideoInclusions.jpgUsing the deck and the card macros of the Composition Plugin, I have created a card for each of the four sections of videos. Then using the Include Page Macro, I have included each page in the respective card on the Confluence Videos page:

Composition.jpgTaking this approach of including other pages in each card of the
deck stops the page becoming bloated with the wiki markup that would be
required to create each section of videos on the same page.

HOT TIP: Display a random Tip of the Day or announcement on your Confluence pages using the free Include Random Macro

Using a set of bundled
and free plugins we’ve been able to create a space that pulls
information from existing spaces and leverage a single set of content
across multiple pages in the same space. This eliminates the sales team
duplicating the efforts of the Technical Writing team if we were to
re-document existing content. Organising this information in a logical
way allows us to deliver the content to evaluators more effectively and
to easily maintain that content to ensure it is kept up to date.

Next week I’ll be publishing Part 3 of this series, teaching you all how we went about creating the Confluence FAQ’s. Stay tuned!


Plugins Mentioned:

The simplest way to install plugins for Confluence is by using the Confluence Plugin Repository.

Articles/Sites Mentioned:

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now