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

Answer questions before they are asked

Part 2 of this blog series focused on how the content in the Confluence Evaluator Resources
space has been carefully organised in an inclusions library to avoid
duplication of content. This instalment explains how we created the frequently asked questions section of the space.

Why did we need a FAQ?

Being the first point of contact for evaluators of our products, Sales Engineers are asked a lot of questions. Naturally, some questions are asked more frequently than others.

Our Technical Writers do a fantastic job creating and maintaining the Confluence Documentation space.
Here, you can find the Confluence Administrator, Configuration and User
guides along with a whole bunch of other useful documentation for the
latest release of Confluence. Similarly, our web team have created an
awesome website with a seperate section for Confluence where you can learn all about the product in our feature and solution tours, as well as find all our licensing and pricing information.


Now, while we have all of this really useful information publicly
available, the Sales Engineers still answer questions that are already
answered, whether it be on our website or within the Confluence
documentation, on a regular basis. Why? Sometimes it’s just easier to
ask, rather than trying to find an answer and it can also be hard to
find the answer when it is not represented as a question. You know the
question you want the answer to, but the answer to that question is
often hidden amongst a sea of other information.

The Sales Engineers decided to use Confluence to deliver a list of
FAQ’s from Confluence evaluators to answer those questions, before they
are asked. To ensure that evaluators find the FAQ’s, we include a link
in our introductory emails which all evaluators receive when generating
an evaluation license.

Why did we use Confluence?

Remove the bottleneck

Rather than storing the FAQ’s within the Confluence section of our
website, which only a few select people have the skills and permission
to update, Confluence allows us to create
a page for each FAQ. These pages can be easily updated by any Sales
Engineer should a change need to be made, whether that be a simple
grammatical error or a change to the answer itself.

Re-use existing documentation

Quite often, the answer to the question is already documented in the
Confluence Documentation, it’s just not that easy to find. For example,
we are commonly asked, “What happens if someone tries to edit a page at the same time as someone else?”. The answer to this question is already documented, so instead of re-writing the answer and duplicating the efforts of the Tech Writing team, we have used Confluence’s Include Page Macro to embed the existing documentation on the FAQ page. You can learn more about re-using content across Confluence in Part 2 of this blog series.


Links that don’t break

When documenting the answer to a FAQ we will often link to other pages within the space or even other spaces on our public instance of Confluence. The great thing about creating internal links
in Confluence is that the links don’t break if a page is moved, or even
if the name of the page changes! Internal links in Confluence are
automatically updated.

How did we create the FAQ’s?


Rather than have a single, long list of FAQ’s, I decided to organise
them into ten categories, with a tab for each category. This approach
allows customers to quickly find the FAQ they are looking for. You can
find out how to create tabbed pages in Confluence in Part 2 of this blog series.



Rather than have all the Functionality FAQ’s documented on a single page, each FAQ has its own page. This keeps the parent FAQ page
tidy and aids searching, as users can search for individual questions
rather than trying to find an answer on a page amongst a sea of other
answers. In order to automatically list the right FAQ’s under the right
categories, I labelled each FAQ with a category specific label. For
example, FAQ’s that belong under the Functionality category have had their pages labeled with confluence_faq_functionality. Using the bundled Content by Label macro
I can then list all the questions for each category in the right
category, with a single line of wiki markup. See the screenshot below:


There are some cases where a FAQ may fit under multiple categories.
In that event, we just label the FAQ with more than one label. Easy!


One of the great things about using a wiki to document FAQ’s is that
it’s extremely quick to create and publish new content. Unlike a
website, there is no bottleneck, meaning we don’t have to rely on
another team to make changes or additions to the FAQ on our behalf.
When we want to add a new FAQ all we do is copy an existing FAQ under
the category where we wish to place the new one using Confluence’s copy page function.
This creates a new page under the same parent page and also copies
across any labels. Then all we have to do is change the title and body
of the page to capture the new FAQ. It’s that simple.

CopyPage.jpgNote: We used the same process for creating the Hot Tips section of the Confluence Evaluator Resources space

What else could we do to improve the process?


There are times where you want content to be approved before it is published. If that is the case for you, there are a number of plugins which allow you to set up workflows for approvals of content in Confluence.

Fresh Answers

It’s important that content in a wiki is relevant and kept up to date. Using a plugin you are able to automatically or manually archive pages
within a Confluence space to ensure that your content is fresh. This is
especially important for content such as FAQ’s, as answers are likely
to change over time.

What’s in store for Part 4?

The Sales Engineers are currently reviewing the entire Evaluator Resources
space with the goal of creating a new framework for the space to
provide a consistent look and feel and solid set of resources for all
products. You guessed it, we’re using Confluence to collaborate on the project! I’ll be publishing Part 4 upon the completion of this project.

Thanks for reading!

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

Subscribe now

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

Subscribe now