How to set-up an easy to maintain user guide in Confluence

How to set-up an easy to maintain user guide in Confluence

Let’s face it – long, boring text user guides can be a pain for end users to digest and can raise more questions than answers. As part of the IT team at Valiantys, I’ve found that if users don’t know what steps they need to take under which circumstances, they won’t be autonomous in their work; instead of coming to me to explain whatever system they need to navigate, they’ll come to me to explain the user guide. This obviously defeats the purpose….

As an Atlassian Platinum Solution Partner, at Valiantys we use the same tools we deploy for our clients, which consist of over 4,000 companies across the world. Confluence is our Enterprise Content Management solution, where we host our knowledge base to share our processes and documentation. In this space, the IT team created a user guide to explain how our video conferencing equipment works. While the exhaustive content was crystal clear to the IT staff, I understand that our non-technical users might feel like this:

Despite this, we do have to be thorough. We have different video conferencing equipment across our 11 international offices. Some people organize meetings, others only need to know how to join them. They may be in one of our offices’ conference rooms or trying to join on the go. How do we explain everything while keeping it clear and simple?

We decided to focus on the user, and realized that we needed to adapt our documentation in order to present only the information the reader needed  – and nothing more. Fortunately, Confluence provides several methods for solving this use case.

Making Confluence user guides

Our first solution was to start with a table, and then created filters that would allow the user to narrow down to their situation.



As you can see it worked; we provided the link to the guide matching his situation. Yet it wasn’t entirely satisfying, especially given what Confluence is able to do. It looked odd and surely could be improved!

We decided to make this a dynamic form using an app called  Bob Swift Run macro. We can now present the same information as in the table, but in a much nicer way!


Our users are now happy and our “Video conferencing assistant” looks nice, but it ended up being difficult to edit and maintain when changes and updates were needed.  To remedy this, we moved all the data we frequently changed (access PIN, the list of meeting IDs, dial-in numbers, etc) in different includes, and call them using the Multi excerpt app.

It resulted in a single page, which is easy for our IT team to maintain and even easier for our users to understand.


It’s simple and straight-forward, but then again the best solutions usually are. For more tips on the Atlassian ecosystem, take a moment to subscribe to our monthly newsletter below.

Cutted Triangle

Subscribe to the Valiantys Newsletter

Registered request ! Subscribing... This is not an email An error occured

In accordance with our privacy policy, we are committed to respecting your personal data.

Contact us

Our Atlassian certified consultants will be happy to answer you.

Join us

We're building the next dream team - Are you in?

Follow us

We use cookies for the operation of our website. This is to improve its use, to personalize your experience, and to compile visitor statistics. By continuing to use this site, you consent to this policy. You can manage the settings and choose whether or not to accept certain cookies whilst browsing. For more information, see our privacy policy. Our privacy policy

Privacy settings

In order to facilitate your navigation and to provide you with the best possible service, we use cookies to improve the site to the needs of our visitors, particularly according to the number of visitors. For more information, please read our privacy policy. Our privacy policy


Google reCAPTCHA is a system designed to distinguish humans from computers, so that bots are unable to maliciously fill out forms on behalf of a human being.


Used to send data to Google Analytics about the visitor's device and behavior. Tracks the visitor across devices and marketing channels. Used by the social sharing platform AddThis to store the user's usage history of the AddThis sharing widget. Registers a unique ID that is used to generate statistical data on how the visitor uses the website.


Targeting Cookies: Targeting cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertising on other sites. They are based on uniquely identifying your browser and internet device. You can turn off the use of cookies for targeted advertising here. When the button is green, targeted cookies are on. When the button is red, targeting cookies have been turned off.

Social Media Cookies: These cookies are set by a range of social media services that we have added to the site to enable you to share our content with your friends and networks. They are capable of tracking your browser across other sites and building up a profile of your interests. This may impact the content and messages you see on other websites you visit. If you do not allow these cookies you may not be able to use or see these sharing tools.