Guide to using confluence: organisation and structure

We have decided to use Atlassian’s Confluence system for our internal wiki / knowledge base (KB). This system is often referred to in our internal documentation as:

  • IT Wiki
  • IT Knowledge Base (KB)
  • IT Confluence

If you see any of these references in an SOP or other documentation, then rest assured, it is in reference to our Atlassian Confluence system.

What is Confluence?

Atlassian’s Confluence software is “enterprise knowledge management system”[1]

Essentially this is a set of web pages containing information that is developed, edited collaboratively and ultimately managed by its own audience. (see definition of wiki [2]).

Note; Atlassian is a commercial company. One of many product offerings they have is Confluence.

Atlassian Revenue $1.61 billion in July 2020 [1]. as a result, there are many aspects that are paid for. Some simple functionality that you would expect to be standard, is actually a paid for option. As you will see in the following demo. (Hint: Archive a page is a paid for option)

This is not necessarily a problem, you just need to keep track of the paid for plugins and extensions so you can manage your monthly/yearly costs.



Why use Confluence?

Confluence is a large system with many functions. In the past, I know confluence has been setup to be used in many areas of of our IT team, including managing clinical trial build and progress etc. We are not going to be using Confluence for this in the initial stages, We are going to be concentrating on using confluence for two main functions:

  1. Knowledge Base (How-to Articles) [skip to section]
  2. CPD training session [skip to section]

Both these functions are interconnected.

Knowledge Base

Provide material for reference on various internal IT tasks.

CPD Training

Our monthly training schedule for up an coming sessions. Each session, should, ideally, have a corresponding wiki page. This means that each CPD talk will have some reference material to look back on after the session.

Access Confluence

To access you navigate to your instances url, if hosted on Atlassian servers, you url will mostly like be of the format

This will land you on the main home page for your confluence system.

You can see there is a lot of pages, information and options. Our particular confluence instance needs a bit of an overall, as we are not using it now, as it was intended to be used when it was setup.

Some content need archiving, and things need a bit of a tidy up. Rather than spend several months tidying this up, we will work with what we have for now, and try to be more organised and systematic moving forwards.

In the mean time, I have created a list of important pages.

For the purposes of this introduction, and our evaluation of confluence, we will be concentrating on 2 main pages (as mentioned above):

  1. Knowledge Base (How-to Articles)
  2. CPD training session

We also use the system for Compliance and Regulatory Standards

Compliance and Regulatory Standards; table of reference of the standards we need to keep up to date with, date of last reviewed and update alongside the related SOPs and Forms.

Covering the two main functions of confluence should get us up and running with confluence to the point we can evaluate if it is something we find useful, and if we want to continue using in the future.

How-to Articles

In this part of the guide, I am going to concentrate on the ‘How-to Articles’ section.

I will provide an overview, and also explain:

  • How to add new articles to this section
  • How edit, update content and formatting.
  • How to use the tagging feature
  • Exporting as PDF

Navigate to the url to access your How-to Articles page.

Add new article

On the main How-to Articles page, click the ‘Add how-to article’ button.

This will bring up a menu to enter the title of your new how to article, along with some associated labels.

Although the format of the title and labels are up to the author, if we follow a consistent format, it might be easier for us to use.

I have used the format, topic-101 to indicate an introduction article to the particular topic. The ‘101’ guide will typically explain the basics, and provide enough information to get up and running.

The labels you can assign to your article, are again up to the author. As long as you pick labels that are relevant to the article, this should help up all navigate and search for content.

The title and labels can be edited after you create the article, so you don’t need to get it perfect on your first go.

Note: by using this ‘How to article’ button to create the article, you are essentially using a pre-built template. This template includes the ‘kb-how-to-article’ tag.

Editing and formatting content

Editing and formatting content using confluence is similar to using Microsoft word.

Once you have entered the edit mode by clicking the pencil symbol from the menu.

You will see the top menu bar change to look more like Microsoft word. You have options to bold, italic and colour text etc.

There are a few components within the page that are automatically generated, assuming you used the ‘add how to article’ button to create the page.

The components I will cover in this guide are:

  • Table on Contents
  • Related Articles
  • More options
  • Markdown markup

Table on contents

This component automatically renders to display sections within the article.

The related articles section will use a list of user editable tags to show related articles.

More options

I invite you to play around and explore more options from the menu

Markdown markup

Note: advanced users who know how to use markdown markup, can use the majority of functionality within the confluence edit page setup.

For example, the most commonly used for me is probably section, sub-section, sub-sub-section etc.

# Section
section one

## Sub-section
sub section one

### Sub-sub-section
sub sub section one

Tagging feature

You can modify and add additional tags for an article at any time. When creating new tags, have a quick check you are not creating duplicates. The convention we have is lower kebab case labels.

Exporting as PDF

If you click an article, you and read and also export as PDF, if you need to send the guide to someone who does not have access to confluence.

Once you have selected to export as PDF, you will be taken to a page to download your PDF document.

CPD Sessions

This is the page which contains information on our CPD sessions.

On this page, you can see a list of the types of CPD sessions that we will be running as part of our department.

  • Formal training
  • Demos
  • Event or conference (show and tell)
  • Problem solving sessions (take a common problem, hash out ideas for a solution)
  • New technology/technique discussion (found some new shiny tech?, we can discuss)

This page also contains a table showing our CPD schedule. This table contains the date, host and title of the CPD session taking place. This table also contains the type of CPD, this is to try to help decide if this is relevant for you or not.

Add/update schedule

If you would like to add or update the CPD schedule, you can do so by editing the page.

If you scroll to the top of the page, you should see a menu bar that looks like this

There are various options; like, comment, watch, favourite. We want to click the pencil symbol option to edit the page.

Once you have entered the edit mode, you will see the top menu bar change to look more like Microsoft word. You have options to bold, italic and colour text etc.

When updating or adding a new item to the CPD schedule, there are 3 main advanced elements we need to be familiar with.

  1. Input date
  2. Insert username
  3. Link to document

Input date

Insert username

If you have any questions, please get in touch. I would be glad to help out if I can.

Creating your first programming language is easier than you think,
...also looks great on your resume/cv.