Confluence Configuration Best Practices

When an organization first installs Confluence, it is a blank canvas. The user has little to no structure to build from; There are no spaces, page trees, parent pages, or child pages. There is a concept of spaces but within these spaces are structures without actual content. As a space administrator, it is important to know Atlassian Confluence configuration best practices so you can keep your space (and the rest of the Confluence instance) tidy. Equally important, it’s essential for system administrators to train users on Confluence best practices. Similarly, as a power user, it’s important to follow best practices so that when you produce content it’s efficient, not time-consuming, and easy to find.

In the following sections, we discuss the core concepts of Confluence’s best practices. As we present these concepts, we also provide three personas to these best practices: system administrator, space administrator, and power user. Depending on which persona you fit into will determine your actions for implementing and configuring these best practices.

Spaces and Structure

As a rule of thumb, spaces should be reserved for teams and projects. Every team should have a space to work in and every project should have their own space (especially if it involves cross-functional teams). For example, if next month’s project requires collaboration between two different departments, creating a space for the project is ideal. However, if the project is NOT cross-departmental, it’s best to keep it in the needed department’s space.

Within Spaces, pages are organized into trees. Depending on where you are in Confluence when you decide to create the page, determines where your page will be in the hierarchy. In the image below, you can see an example of a page tree hierarchy.

Based on the page tree hierarchy above, if you decide to create a page while on the page “2019-07-29 Meeting notes”, then “2019-07-29 Meeting notes” will become the parent of my new page, and your new page will be below it in the hierarchy.

As a system administrator, keep track of spaces as they are created and reach out to any space administrators whose spaces you think are redundant or not useful. For space administrators, make sure the content created in your space stays on topic with the overall theme of the space. Lastly, as a power user, think carefully before creating spaces and consider all your options before choosing which space to create a page.

Page Templates and Blueprints

Templates allow you to create content faster and with a consistent structure. Some templates even come with an index page that helps keep your content organized and easily accessible.

As an administrator, train your users on the most useful out-of-the-box Confluence templates. For us, these include:

  • Meetings Notes
  • File List
  • Product Requirements
  • Retrospective
  • How-to Article

Keep in mind that companies operate differently and these Templates that work for us, may not be the best fit for your organization. Take a look at the complete list of Confluence templates and decide for yourself which ones are most useful for your team. If you can’t find what you’re looking for, try creating your own Template. Refer to our blog around page properties and page properties report macro to get ideas on how to create your own index using your Template.

It’s important to note that creating a Template will not require any development expertise but creating a Blueprint will require prior knowledge of Velocity and Java. The alternative is to use an app like the Blueprint Creator (Advanced Templates) app which enables you to build Blueprints in the UI, and allows you to delegate control of Blueprints to Space Administrators.

As a system or space administrator, you can create custom templates and blueprints to help your users create pages faster. Learn from your users about what common pages they are creating and see if you can add a template for it. As a power user, familiarize yourself with Confluence templates and blueprints and how they might apply to your daily Confluence use. Additionally, keep an eye out for new templates and blueprints as they are released.

Macros

Although macros may sound complicated, many Confluence macros are actually very simple to use. It’s important to train users to understand the capabilities and usefulness of these macros. Atlas Authority recommends the following:

  • page properties
  • page attachments macro
  • status
  • excerpt and excerpt include
  • page tree
  • page index
  • anchor
  • Jira macros
To link pages within your Confluence site, the excerpt and excerpt include macros go hand in hand. Since all of your information is in one place, it’s important to reduce redundancy. If you are creating a new page and a separate page already exists with information you would like to add, simply link it or add the excerpt macro to the source page. Additionally, you will also need to add the excerpt include macro in your new page. Your source page macro will look something like this:
Then you can display the information from the source page on a new page which will look something like this:

Labels are a good way to categorize the content on your site. Should your organization decide to use labels, we suggest training your teams on related labels and popular labels macros. With these macros, it helps users quickly find the information they are looking for and intuitively guide them through your knowledge base articles.

Therefore, it is vital for a system or space administrator to train users on what macros are available and how to properly use them. As a power user, it is your responsibility to use macros to reduce redundant content on your organization’s site. Using macros also helps keep your content looking tidy and fresh.

Attachments

Another important training activity to onboard users is helping them understand the best way to upload files or attachments. The Confluence search is so powerful that it can actually search the contents within the attached PDF and Word documents. However, this only covers two types of attachments. Therefore, an easy-to-search naming convention is highly recommended for your attachments. We suggest that the name is clear and explains what each attachment contains so that the user doesn’t have to open more than one attachment to find what they are looking for.

The file list template is another useful tip when using attachments. Within each space, you should have a file list template page that contains all of the attachments for that space. If there are too many attachments for one page then you could have multiple file list templates for different page trees. From here, if you need an attachment on your page, you simply add a link to that page. This way, all of your attachments remain organized on one page and makes it much easier to find if you can’t search for what you’re looking for.

Confluence will automatically version your attachments. The only requirement is that you upload them to the same page with the same name. This way, Confluence serves as your version control software as well. You can access attachments and their versions by clicking the attachments icon at the top of the page.
The most recent versions will be presented like this:

If you are a system administrator, train your users on attachment best practices. If you are a space administrator, keep track of where attachments are going and how they are displayed in your space (index page). If you are a power user, make sure to upload attachments to the index page and then link attachments to your page.

Confluence Best Practices

Regardless of your role as a system administrator, space administrator, or power user, following these best practices will help you keep your sites, spaces, and pages, updated and engaging for users to follow and read. Contact us to let us know if there are any best practices we missed or if you need help configuring or organizing your Atlassian Confluence knowledge management site.