Confluence Templates are one of those things where the Atlassian team outdid themselves. The wide variety of ready-to-use pre-populated pages covers all business, development, management, and design needs.
Yet sometimes, we need a template tailored specifically for our project (Product Requirements, Integration Instructions, Project Passport, etc.). If it’s possible to make a few slight adjustments to an existing Confluence template, then great — you don’t need to read further. Otherwise, you have to develop both the structure and the content by yourself.
And in this article, we will take a look at some strategies that can help create more user-friendly templates from scratch.
User-friendly for whom?
Before suggesting any tips or tricks, let’s figure out who is the user that we promise to make templates friendly for.
There are 3 of them and each one has particular expectations for user-friendliness:
So, we will try to address everyone’s demands (even though you can't please everyone).
Prepare the width
In one of the recent releases, Confluence introduced the feature that allows making a template full-width 🤩.
Not that this particular feature contributes a lot to the user experience. It’s just worth mentioning because some of the following strategies require the full width.
Avoid mentioning people
It was a real-life case that taught me this lesson.
I was asked to create a Product Requirements template, and at the very top of the page, there should be a so-called Approvals table. In this Approvals table, people with certain roles (who make decisions about the Product) have to put their verdict on the requirements — approved or rework.
It was necessary to specify not just a role that has to approve the doc but a concrete name so that to understand who to approach for answers and clarifications. Since the group of approvers has not changed for a very long time, I decided to mention all of them in the Approvals table:
I thought that it won’t be a big deal to fix just one template in case anybody changes their position. What I didn’t think about was:
🤔 What if there will be several templates with similar Approvals tables and the same approvers? (so, it’s more than one template to edit)
🤔 When somebody creates a new doc based on this template and publishes it, all approvers receive a notification. It’s unlikely that the specification is polished and ready for review after the first publication. But approvers won’t get any notifications unless they make themselves watches for the doc (which they won’t do).
So, the problem is that approvers receive a notification at the wrong time. It would be more convenient to get the notification right after the final version of the doc is ready for review.
As a solution, I suggest the following alternative:
- Create a page where to mention all approvers — their roles and names.
- In the Approvals tables of templates, paste a link to the page with approvers on every mentioned role. After each role, put a placeholder with the text @EmployeeToMention so that it’s clear where to specify concrete names.
- Under the Approvals tables, put a placeholder asking Template Utilizers to mention concrete people only after the doc is ready for review:
In this way, we
- for Template Creators, simplify the process of maintaining templates with the Approvals table;
- don’t annoy our approvers (Readers) with not-in-time emails;
- add some extra work to Template Utilizers, but this extra work pays off in effectiveness of the approval procedure.
Don’t overdo with layouts
When it comes to layouts in templates, less is more! There is nothing wrong with playing around with different layouts for different parts of a template. The question is how energy-consuming it is for the Template Utilizer to stick to the selected layout while filling out the template.
Let’s consider the following requirement: in a template, there should be a section dedicated to UI/UX requirements for a feature (ultimately, in this section there will be several sketches for designers to reproduce in their design tool). The section must include:
- a space for a sketch
- requirements for Designers (text length limitations, color palette, etc.)
- links to similar designs from competitors
- link to the corresponding Jira task to track progress
As a Template Creator you came up with the following structure for this section:
Is it beautiful and aesthetical? Maybe. Is it practical and convenient for a Template Utilizer? Not so much. Why? Because if there are 10–20 sketches to put into a document, the Template Utilizer will have to bear in mind the developed structure: they need to pay attention to the layout, maintain it for every sketch, and perform additional manual activities of copying and pasting. And all they want is just to put the next sketch below the previous one.
So, don’t try to impress anybody with your creativity and out-of-the-box mindset in laying templates out. Make it as simple as possible (for instance, as described in the following paragraph).
Consider tables for the main content
According to my experience, people love working with tables. They are simple, visually structured, and intuitive when it comes to filling them out in templates.
Getting back to the previous example with UI/UX requirements sections in a template, let’s consider a different approach by using a table:
To some, this second option may not seem as attractive as the previous one, but it still serves the purpose. And, most importantly, it’s more intuitive and less consuming for Template Utilizers to fill in the table.
Insert a table of content (if needed)
If your template consists of several sections, consider incorporating a table of content. In this way, you will make articles created based on the template more readable and easy-to-navigate.
For example, in a basic Software Requirements Template, there can be the following sections:
- Approvals
- Product Requirements
- Functional Requirements
- Transition Requirements
- Open Questions
Yet we have only 5 sections here, each of them can expand when a Business/System Analyst (or another dedicated person) creates a Specification based on this template. In a large canvas of generated text, it’s hard to quickly find something if you don’t know exactly where to search and whether or not it’s there in the first place. So, the table of content will help to get an idea of what to expect from the document:
Polish messages in placeholders
Placeholders are supposed to help Template Utilizers fill in templates easily. Therefore, messages in placeholders must be concise and unambiguous.
In some cases, messages are obvious and they actually could have been avoided:
But sometimes, it’s not very clear what a Template Utilizer has to put in a template section:
For such non-obvious cases, I would recommend the following strategies to use when creating texts for placeholders:
- put examples of what is expected in a section:
- create several alternatives for a text and test them on a focus group (the focus group should consist of Template Utilizers)
- if it’s hard to explain what is expected in a section, consider renaming the section itself
Add some info macros
Info macros (info panel, tip, warning, note) help attract Readers’ attention to critical points in a document.
A lot of Confluence templates beautifully incorporate them, so you have an example to follow:
You can use these macros depending on your intentions. Here is how I decide when they are necessary:
- info panels (blue boxes) — for definitions and references to external resources
- notes (violet boxes) — for non-trivial use cases worthy of attention
- success panels (green boxes) — for tips and final results of procedures
- warnings (yellow boxes) — for restrictions, limitations, and potential mistakes
Describe your templates
When you finish your template, it’s obvious to you who will be Template Utilizers, what exactly this template serves for, and where docs created based on the template must be stored. But all those things are not that obvious to your colleagues.
Take a few minutes to develop a concise (only 100 symbols are allowed) yet useful description for your template, mentioning:
- what does the template contain;
- which roles are supposed to use the template;
- where to create and store documents based on the template;
- some other details relevant to the template.
If you also have effective strategies that help create user-friendly templates from scratch, please share them in the comments 😃
