Starting with Confluence for document publication or project management

Every team and every project have slightly different approaches to risk management and general documentation but on any project these are crucial. In addition to the numerous various approaches, there are as many tools available that can be used. The past year I, in my roles as business analist and scrum master, have primarily been using Confluence (in combination with JIRA) as the core tool and am sharing some of the things I learned to hopefully help those of you that are just getting started with it.

The risk management and general documentation scenarios I will address are:

1. Using Confluence to structure documentation across different channels
2. Using Page Properties Reports in Confluence for overviews
3. Using Confluence templates

1. Using Confluence to structure documentation across different channels

On my current project but also on previous projects, Confluence was selected for documentation after the project had already been in progress for a little while. This resulted in existing (Visio, PDF, Excel, PPT, etc.) documents needing to be somehow made visible in Confluence while minimizing rework.

The approach I used to implement Confluence on these projects involved the following steps and for each there are some lessons learned.

i. Identifying the core components of the document (starting from going through the table of contents)

Lessons Learned: Often the Confluence table of contents was very similar to the original document.

ii. Determining which of these core components were best suited to be reconstructed visually in Confluence.

Lessons Learned: Documents that need transferring to Confluence can be text heavy, for documenting in Confluence focus on visualization. Present information in tables, use icons or other graphics, summarize chunks of texts (for example with bullets), and ensure large images such as process flows are uploaded as PDF for optimal display (Confluence has a special PDF display function that allows for zooming in and out).

Confluence also has lots of different ways for linking and importing. If you are documenting scenarios, insert links to the relevant User Story and Epic in JIRA, this creates cohesion and easy access across the platforms. Inserting the original document as an object on a Confluence page or linking to other locations such as SharePoint is also always an option.

iii. Creating the required structure in Confluence

Lessons Learned: Ideally Confluence pages are easy to view and self-explanatory, so it is important to consider which sections require separate pages. For example, having multiple large visuals on one Confluence page causes the page to feel too long and crowded unless you use the expand function properly.

iv. Filling in the content

Lessons Learned: Ideally you start using Confluence from the start and focus on creating any templates and deliverables in this tool as much as possible from the beginning if it is the final place for documentation. Copy – pasting is otherwise inevitable.

2. Using Page Properties Reports in Confluence for overviews

Recently I created several pages in Confluence, one page for each process scenario. They were grouped under the relevant interface, but it still looked a little messy. Page Properties Reports allow you to create a nice overview of several pages (such as scenarios for an interface) which are really nice to use when you need a cover page for a section.

Creating a page properties report starts with two key things. Labelling each page that needs to be included in the report using the label function and determining what information you want to display in the report. Once you have labelled all the pages (for example scenario1, scenario2 etc) you then have to insert a Page Properties section on each page. Thinking about what you want on a cover page, I often include information such as Status or Jira Story number.

Once you have created a Page Properties section you can then on your cover page insert the Page Properties Report. This report can also be customized to include information such as when the pages were last edited, or who created the page – all useful information for an overview. This helps keep your pages organized and easy for others to understand and find information.

3. Using Confluence templates

A big benefit of a widely used tool such as Confluence is that you don’t need to reinvent the wheel. The first thing you see when you are creating a new page is a templates search bar on the right. Use this!

There are great templates, from normal note taking (action tracking, decisions), to retrospectives, and product roadmaps.

Hopefully these few insights help you get started with Confluence on your next project. If you are interested in more information, this Confluence Fundamentals training by Atlassian is an additional great source of tips and tricks.