OddPen

One of my most controversial opinions is that I have a soft spot for Confluence. But wait, let me explain it a bit further. I understand all the pain people have with it. I get it. I'm usually in the same boat. However, I do not think it's Atlassian's fault for providing a better UX. For many things, it is just administrated and used poorly! Or, to put it in simpler terms, Confluence needs to be utilized correctly.

I do not want to discuss this further in this post, but I want to provide an excellent example of what you can do with Confluence. This already implicitly covers my main (opinionated) arguments for my stance on the discussion.

The Use-Case

One of the most common things people want to do in Confluence is to have a list of recurring posts. Picture meeting notes, workshops, etc. Usually, they have these requirements:

• a structured template for a post
• an overview of the posts
• a complete/detailed post
• having that data searchable
• good UX to add another item

What we want is a list of notes that share the same structure. For example, all of them should serve an agenda, a date, a list of participants, and so on. They should be organized in a structured overview to be easily scanned and searched.

The Problems

I discovered that many teams (or even organizations) struggle to have a good concept for this everyday use case. The problems are often the same:

Bad UX of Adding a New Entry

That's probably the most annoying issue. The concept of adding a new entry is quite often to copy a portion of the page. This comes with various problems: It's unclear what to copy, formatting issues are cloned, copying on a slow page (and such page is getting bloated, thus slow over time) is cumbersome, specific formats are cluttered and need to be manually fixed, etc. Wouldn't having a “Add Entry” button be nice instead?

No Overview

It usually gets confusing when all the entries are pushed into one page. The information is all over the place, you can't keep track, it's hard to find and filter entries, the page gets slow, and the structure is not visible from the page tree. It's also hard to distinguish between general and detailed information. Latter is not necessarily needed prominently in the list, yet you have no choice.

No Clear Blueprint

Having a blueprint with mandatory information is relatively easy to maintain initially. People commonly add a table with respectively labeled columns. However, as the lists progress, columns might get removed, renamed, added, formatted differently, interpreted, copied with flaws, and so on. The needed information more and more get ambiguous. And the lower the quality of the entries, the more people feel demotivated to maintain the same in the upcoming items. Do you also have a list with missing and low-quality data in the rows? Didn't that list start out pretty ambitious and well-thought-out, only to be neglected after a while?

Making it Work

Now comes the fun part. We solve these issues in an exquisite and convenient way. We use custom templates, the table of contents feature, the excerpt macro, task lists, and a button to add a new child page.

Adding a Template

The first thing we need is a template. That's basically a prefilled page representing our recurring document. Let's stick with meeting notes for our example.

ℹ️ Info
Explanation on how to exactly add a template is beyond the scope of this post and varies heavily between the different Confluence versions. However, you can always head to the official Atlassian documentation and read about it there.

First of all, you need to know these things:

• What information is needed on the blog post as a whole?
• What information is known upfront or mandatory?
• What information is needed in an overview?
• The basic outline and layout of your post.

Based on this, you can create your post template. What we do now is create a blank template. First, we are going to add variables to the page. To do so, open the add macro dialog (macros are called slash commands in the newest versions) and choose “New Variable.” Do this for every mandatory information that can not be automatically (computational) evaluated, and the author knows upfront. Let's say, for example, the time and date the meeting will take place. Don't overthink it at this point. Our template can be further optimized and adapted as time moves on. All we have to do now is further build (or set up) the post template. Add the needed sections, fields, placeholders, headlines, and whatnot. Follow along with the official documentation in case you need help—attention to the “Instructional Text” and “Template Variables” chapters. There is one last step you need to do now: add an excerpt! To do so, choose the excerpt macro (or slash command) and add it. Now place everything into the box needed for a basic post overview. Commonly you'd refer to this as “header data.” For meeting notes, it can be, for example, the date of the meeting, participants, agenda, etc. Only add a little. Be very cautious not to overload the excerpt. Further information and a detailed guide are here: https://confluence.atlassian.com/doc/excerpt-macro-148062.html. The idea is that we, later on, show this exact excerpt in the overview. This can be easily done with a specific macro.

⚠️ First Confluence Pitfall: Do not restrict users from adding templates! They are a crucial part of the app and are meant to be dynamically used.

Adding a Parent Page

Now we want to have a parent page. Think of this more as a “folder” than really a page. The difference to a directory as we know it from operating systems is that it's quite feature-rich. We can provide any content we want, including an overview of child pages! That's precisely what we do now. First, add some meta information to your page. Let's say a title: “Meeting Notes of Foobar!”. You can do whatever you want and need. Add a header image, disclaimer, intro, or whatever. Now comes the critical part: the child-page macro. Add it where you want to have the overview of past meetings and configure it like so:

• Excerpt Display: Rich Text
• Heading Style: Something that suits your document, but the second level should do the trick, usually
• Sort Children by: Creation
• Optional – Number of Children: Normally, you want to restrict the child pages displayed For meeting notes, it's often a good idea to set this to three. It would show the currently open notes, the preceding meeting, and one additional for reference.

More usage information here: https://confluence.atlassian.com/doc/children-display-macro-139501.html

Mention the “Exceprt Display” option. This is where you tell the macro to show the page excerpts. Remember how we added it to the template? The option “Rich Text” shows the content precisely like on the page (otherwise, it would be transformed into a text-only version).

⚠️ Second Confluence Pitfall: Pages are directories, not documents! Please do not use them as you would with a word processor (or whatever is used to create a content-complete PDF eventually). Generally, it would help if you strived to have many pages with little content. The same goes for spaces. There is no one fits all solution, but often spaces are defined far too broadly.

Okay, now you should have a list of child pages that, more or less, looks like you'd have added their excerpt content to the just added page. You can try this out by adding a few example pages (they don't necessarily have to be created from the template from the first chapter). Now we need one additional thing. Add the macro “Create from Template.” We use it to have a button to create a child page, so a meeting note. Configure it like so:

• Button Text: Set this to your needs, e.g., “Add Meeting Note”
• Template Name: The Template you have created in the first chapter
• Title of the Page to be Created: Set this to your needs (be aware that you can use variables here), e.g., “Meeting – @spaceName on @currentDate”
• Space Key: the key of the current space (usually defaults to that already)

More usage information here: https://support.atlassian.com/confluence-cloud/docs/insert-the-create-from-template-macro/

⚠️ Third Confluence Pitfall: Don't consider Confluence to be a document silo. It's not Google Drive. Try to utilize dynamic tools and macros as much as possible. Try to use it as a no-code front-end platform rather than a document management system.

Bonus – Task List

If you plan to keep track of the pages' tasks, you may also consider adding the task report macro. It lists all the tasks on a particular page and its child pages. In our case, that would be our newly created parent page.

Conclusion

With this approach, you have an easy way for users to add a new post with a given format. You have a very easy-to-scan archive of posts and keep the overview performant. It mitigates the problems we addressed in this post. You may want to read through them again now. Please also take this opportunity to rethink how you utilize the tools you have within Confluence! Get creative. 😊 The features are meant to be used!