Here’s Why Your Confluence Instance Is Disorganized

April 22, 2021
#Confluence Tutorial#Confluence
10 min

Are you having trouble managing your content in Confluence? Is it difficult for users to search for a specific page or attachment? Do your teams have a hard time staying on top of important information? Or maybe your Confluence user adoption is at an all-time low?

Then your Confluence may be disorganized.

A lot of admins struggle to keep their Confluence organized, especially when the volume of content increases. With more information to manage, attachments to keep track of, wikis to groom, and a larger user base to administrate, it’s normal to feel overwhelmed.

You may not know where to start reorganizing and decluttering your instance, but identifying the reasons it’s disorganized in the first place is a great first step. From then onwards, it’s all about implementing the best practices and charting a Confluence management strategy that supports your business needs.

Continue reading to find out the causes of a messy Confluence and the most effective way to detangle the mess.

Cause #1: Inefficient space management

Confluence space structure says a lot about an organization. Without a clear structure, you will have a hard time arranging content and also make it difficult for users to navigate the wiki.

confluence space with no page structure

Setting up a lot of spaces without any form of categorization isn’t practical. It can crowd your wiki, reduce the searchability of content, and prevent users from staying on top of critical information.

On another note, spaces that store outdated information could mislead users looking for the latest updates. So, what can you do?

Structure spaces based on your needs

Start by structuring spaces around people and/or work. You can set a space for each team – development, finance, sales, content, marketing, HR, etc. Then, make sure to categorize your spaces using labels. Consistency in labeling must be prioritized here since you have to add them manually. Use the page tree feature to compartmentalize content and information into relevant sections like knowledge base, team calendars, and team OKRs.

If collaboration is more central for your teams, you can create project- or product-based spaces instead. For example, backend developers, who typically work alongside frontend developers, requirement engineers, and product managers, can operate more efficiently and communicate effectively when all the relevant information for a project is in one space.

Next, use Confluence’s analytics to help you identify unused spaces across your wiki – spaces that are least viewed or not used on a daily basis. Archive spaces that are no longer relevant to improve the navigability of content, enable teams to stay on top of critical and new information, and help establish a robust wiki.

archive Confluence spaces you do not use

Cause #2: Inconsistent labels and lack of metadata

When the use of labels is inconsistent, pages, blog posts, and attachments can end up drowning in the sea of content. Even worse, poor labeling causes search results to be irrelevant and inaccurate.

To avoid problems, avoid manual labeling. Having a clear, documented labeling convention can help. But it’s not a perfect system, and you’ll likely end up having to review regularly to address typos and other inconsistencies. Additionally, you’ll need to routinely update the labeling convention as the range of content grows.

The entire process is tedious because Confluence lacks effective metadata management capabilities. Labels are the closest thing to metadata that the platform offers, and even so, they are still unstructured metadata.

Leverage metadata management capabilities

Instead of settling for error-prone labeling practices, you can leverage metadata management capabilities instead. The most effective way to improve searchability, categorization, and organization of content is by using metadata – Forbes has highlighted this as well.

metadata consistency in Confluence

In your mission to tidy up your Confluence, metadata can help you:

  • make global metadata changes to swiftly remove label typos from content, which will then help deliver accurate search results
  • create predefined metadata fields to help users quickly find information by searching for relevant keywords
  • use said predefined metadata fields to pull critical information from a page and display them using Confluence macros
  • prevent users from entering page labels that are inconsistent, incorrect, or typo-filled.

Metadata for Confluence is an app that you can leverage to achieve the goals above and more. By managing your metadata, you can rest assured knowing that your Confluence will remain organized no matter how vast your instance becomes.

overviews based on metadata in Confluence

Cause #3: Undefined page structure

You have a Confluence space for a project in the making, so keeping comprehensive documentation is vital – how do you go about arranging information?

Are you using page hierarchy to categorize it into relevant topics and/or units of work? Is there a clear flow of information from the meeting notes to the quality assurance test? If a new user visits the space, will they get the latest information on the project?

If your answers are mostly “No,” then you don’t have a defined page structure across your spaces.

On the other hand, how do you ensure that all content contributors follow the standard structure of information display? Imagine if you have a set of product requirement pages with a clear format and structure – but when a new contributor comes along, the structure is no longer maintained. What happens then?

Use templates and macros to organize content

Firstly, coming up with a rough idea of how you want to structure your page tree in a space can tremendously improve organization. To do this successfully, you have to consider a few things; the objectives of the space, the longevity and types of content, and the flow of information.

For individual pages, the information structure can actually be maintained – all you have to do is use page blueprints; templates that come with macros, formatting, and sample content. You can customize them according to your organizational needs.

You can also benefit from predefined metadata fields here; you can pull important information from a page and have it displayed in the page overview using macros. This will help users see what’s under a parent page without going into every other page in the hierarchy. The page tree feature will also help you compartmentalize content and information into relevant sections like knowledge base, monthly reports, etc.

If you need to manage documents and attachments in Confluence, try Smart Attachments for Confluence. The app improves how you organize attachments in Confluence, keeping your project documents and files organized the way you want. You can:

  • quickly download your existing folders with files into the space storage
  • embed documents or folders into the content of your Confluence pages
  • collaborate on project assets right in Confluence.

Instead of searching for specific files through numerous Confluence pages, you can rapidly find them in your space storage along with their revisions. Make document management in Confluence a breeze with the help of this solution.

Tidying up your Confluence space

A disorganized Confluence can be a reminder of how vast your instance is becoming. To sustain a bigger Confluence, you need to scale your content management capabilities. That includes leveraging metadata, acknowledging all the platform’s features and limitations, and understanding where you fall short. Only then can an action plan be formed.

To get more insights on how to make your Confluence instance more powerful, check out the Making Magic with Metadata ebook. You can also read about nine Confluence best practices your users should know.

Related posts

Smart Attachments for Jira Cloud Released!

March 19, 2020
3 min

Ladies and gentlemen, we are excited to announce the long-expected release of Smart Attachments for Jira Cloud.

Categorization of attachments is now available on Jira Cloud too. We did our best to deliver the relatively new experience to manage and categorize attachments. The Cloud app differs greatly from the Server app, but we tried to maintain its handy approach to categorize attachments in Jira issues, and we hope we succeeded in this (smile)

The Smart Attachments for Jira Cloud app works with labels that you can use to tag your documents and attachments. The best thing about this is that are no longer limited by the set of pre-defined categories, now you can add labels on the fly and have different labels in issues of the same Jira project.

Due to some technical limitations of the Cloud platform, the app cannot work with the native Attachments section. But this is not a problem, you can quickly access the labeled attachments from the sidebar.

The app lets you instantly filter documents and assets against one or multiple labels. This can be done by selecting the appropriate label from the list or clicking a specific label below each attachment name.

To preserve the “good old style of categories”, we introduced the grouping of attachments by labels. So, practically, you can have the same categories within Jira issues and you can locate your files in the appropriate category at once.

We are expecting to receive feedback from you. Both positive and negative feedback will be greatly appreciated, so don’t wait and start a free trial of Smart Attachments for Jira Cloud right now.

Running Document Management in Jira Like a Pro

January 28, 2020
#How To#Jira#Document management
6 min

The digital era has digested, transformed, and automated the majority of routine processes we got used to. More and more companies are choosing digital products to run their projects and initiatives.

One of the most popular platforms for managing projects and tasks is Atlassian Jira. Documentation is an essential component of the project development life cycle, and the way it is organized is very critical for normal company operation and project success.

A lot of companies prefer integrating their document management processes into Jira, so project teams can always access the documents they need without leaving the context. Unfortunately, being powerful in project management, Jira itself does not provide sufficient capabilities to run the document management processes and neatly organize documents.

The Smart Attachments for Jira app is the tool that can reshape and facilitate your document management workflow in Jira with much ease and convenience.

Categorize documents and attachments as needed

Jira does not provide any separate interface to store and manage attachments. Users just upload them to Jira issues and update these files upon need within issues. The situation gets out of control when ten or more attachments appear in a single issue. This complicates the finding of the required document in a few seconds.

The Smart Attachments app brings categories into Jira issues. Now you can quickly place your documents into the relevant category and find them there after some time. With the configured access restrictions you can keep confidential files hidden from other users right within Jira issues.

It is no longer a problem to upload a file to the necessary category on any form or in any section of Jira. The automatic distribution rules accelerate the bulk upload of attachments to categories with their further sorting.

Design the structure to store attachments

Storing attachments in hundreds of issues can become a real challenge once you need to find a specific document requested by your stakeholders. You may waste hours searching for a specific file among thousands of other files.

The centralized project storage addresses this problem and provides a single point for storing attachments like on your local drive. You can quickly upload all the frequently used or approved documents and assets to the project storage and your teammates can access them at any time. Design the storage structure for your need and upload even folders with attachments with the automatic folder recreation.

Organize revisions under the parent document

While working on project documents and media assets, you can sequentially produce multiple revisions. Several rounds of reviews and updates can lead to a problem with identifying the last version of the document which was already approved by the customer.

Keep your document revisions in a tree-like view and always find the latest revision in a blink of an eye. The app maps files by their names to the parent document, otherwise, you can attach the document revisions manually.

Execute bulk operations on documents and files

Removal of multiple attachments from a Jira issue can be a pain, but what if you have mistakenly uploaded hundreds of files. With the Smart Attachments app, you just need to select the required files or the entire category and choose the bulk operation. That’s done!

A variety of bulk operations allows you to delete, move, email, archive, or download multiple files in a Jira issue.

Automate file validation and routine operations

The human factor is a key to making mistakes in Jira. If you need to validate availability of documents in a specific category, the supplied workflow validators can simplify this procedure during issue transitions. You can check up files against their file names, the number of files in the specific category, or uploaders.

With the post-functions, you can perform routine operations on documents and files when closing issues, requesting approval from stakeholders, or requesting missing files from external suppliers.

Scale the document management in Jira

Document management in Jira can be efficient and easy-to-run. Just try a 30-day free trial of the Smart Attachments app and redefine your document management processes with the supplied features and automations.

Document Management of Project Assets in Atlassian Confluence

August 6, 2019
#Document management#How To#Confluence
6 min

The more complex project you start, the more documents you need to have. All sorts of policies, specifications, diagrams, wireframes, prototypes, user guides, and bunch of other things should be kept somewhere.

When your team uses Confluence for collaboration on projects, it may be quite inconvenient to store projects somewhere else. In this case you cannot discuss them directly with your colleagues, you need to transition to some other service to retrieve the latest revision, and, finally, you lose the context during your discussion sessions.

These issues made us to design the solution that will provide the centralized storage for your project documents in Confluence. We also kept in mind the necessity to quickly navigate among assets, embed them, and perform all the essential operations on them.

All these concepts were successfully implemented in Smart Attachments for Confluence.

Create the project storage and its structure

Start of a new project is always followed by collection of multiple documents, including old project documentation, new specifications, business and project visions, diagrams of all sorts and kinds, and any other stuff that you find.

During the stage of project evaluation and elicitation of requirements, you need to gather all sources of information and add them into the proper catalogs. This way your teammates can quickly and easily review these files in one place.

project storage in Confluence

The Smart Attachments app allows you to quickly create a project storage with all the necessary folders within it. If you have already sorted out all files on your local computer, you can upload all these folders and the app will recreate their structure in the storage. This is quite convenient when you migrate files from some external file sharing service or from SharePoint.

Upload and manage files with ease

When the project is going on, new and new files are added to the project storage. New folders are created for new document types, old documents are deleted, new document revisions are uploaded.

The Smart Attachments app is a great helper for you here. It provides all the essential features for managing documents and assets in the storage. Additionally, it matches all uploaded revisions by name and attaches them to the parent documents. This way you can keep consistency in your files and you can always locate the latest revision under the source document.

Embed files and folders into context of pages

Keeping documents in the space storage is convenient, but usually a team needs to review files, comment on changes, or point out the necessary updates. This usually occurs in the page context and here the app provides a quick way to embed either documents or entire folders with files.

folder attachment macro in Confluecne

You just need to copy the embeddable link and paste it onto the page. The app will automatically catch this link and will convert it into the document or the folder. The embedding of folders allows you to navigate through the space storage, open files, manage them, and even upload new ones without leaving the context of the page.

Review and collaborate on documents

You can quickly and easily review documents with your colleagues, as the app integrates neatly with the inline comments of Confluence. When opening the embedded file on the page, you can comment on it, discuss some ambiguous points with teammates, and propose ideas on how to improve.

If some updates in the document are needed, you can add them with the help of Atlassian Companion app. You can initiate the file editing right from Confluence and save the modified file as a new revision in the space storage. This keeps all your edited files in one place without any fragmentation when files appear on different pages within the space or even spaces.

For better document searchability in Confluence, you can assign labels to your documents. Further, you can look up for these files when performing the global search for files.

Have fun with document management in Confluence

Yeah, this is not a joke. The Smart Attachments for Confluence app can turn your document management approaches upside down.

You no longer need to browse for specific files through numerous Confluence pages. Find them in one place including all their revisions, collaborate on documents in context, and deliver your projects on time.


Document Management in Atlassian Confluence

February 21, 2019
#How To#Confluence#Document management
5 min

Atlassian Confluence is known as one of the best team-collaboration platforms on the enterprise market. Structured organization of pages, as well as real-time collaboration on content, allow people to instantly streamline their ideas, discuss updates with colleagues, and adjust solutions on the fly.

Having such powerful tools and great features, Confluence has one major flaw. It is the retention of documents and attachments in the application. There is no centralized interface to keep attachments. When you start a new project, you deal with hundreds of files and project artifacts that are created throughout the project life cycle. The main problem is that every new document can be attached to the inappropriate page. After some time, this leads to fragmentation of attachments across spaces, and it becomes more and more difficult to find the necessary file.

Centralized Storage for Documents and Files

The Smart Attachments for Confluence app allows you to forget about file fragmentation and improve the document searchability in Confluence. This tool allows you to have a space storage for keeping project documents and files in one place and in the structure you want.

This gives you sufficient tools for document management and control in Confluence. First of all, you can upload multiple folders with documents and files into the space storage. The app will automatically re-create the structure of folders in the target space storage and save documents under the corresponding folders. This way you can quickly move all your project files from your Dropbox, OneDrive, or Box account to Confluence where all your colleagues can instantly see and use them.

uploading structure of folders and files in Confluence

Embedding Folders and Documents into Confluence pages

To collaborate on documents, you can embed distinct files and entire folders into Confluence pages. All you need to do is to copy the embed code and paste it on the page. After saving the page, Confluence will render a document or folder on the page.

attachments in Confluence

When embedding folders, you can freely navigate within this folder and its sub-folders without leaving a Confluence page.

Reviewing and Editing Documents

Embedding documents into Confluence pages allows you and your colleagues to collaborate on documents, discuss updates and changes in them, as well as edit them with the Atlassian Companion app.

While reviewing files, you can add notes on documents pages and images. This way you can request a series of modifications in the document from your colleague.

reviewing and saving documents in Confluence

These modifications can be added into the document on the fly through the Atlassian Companion app. This way you can keep the entire history of modifications in the document, as the Smart Attachments app will preserve the document revisions in the space storage.

Document Control in Confluence

Document management in Confluence can be a simple and easy task with Smart Attachments for Confluence. Get rid of file fragmentation and locate your project files always in one place.

Start a free trial of Smart Attachments for Confluence

9 Confluence Best Practices Your Users Should Know

September 4, 2018
#How To#Confluence Tutorial#Confluence#Document management
10 min

This guest blog was written by Balkis Khouni, an Atlassian certified consultant at Valiantys. Valiantys is a top Atlassian Platinum Solution Partner with proven expertise in DevOps, Agile and ITSM. They have rendered client-tailored services to over 4,000 companies, providing expert guidance on the deployment, adoption and support of Agile tools. To find out more, visit

Confluence is a content collaboration software that helps teams create, share and discuss their work. One of the tool’s characteristics is it’s simple and user friendly interface, yet also provides all the necessary features to organize and structure your company’s content on one single platform.

Because of the tool’s simplicity, it is easy for users to add content without following good practices or guidelines, resulting in an unstructured wiki which can be counterproductive and hard to browse.

It is highly recommended to define a list of guidelines for your users, so they know how they should structure content within Confluence. Below are some general best practices which will help optimize your company’s use of Confluence and make information sharing a breeze for everyone. While these tips are geared more towards day-to-day usages, for further information on how to make Confluence a fully-fledged Enterprise Content Management solution check out this guide from Atlassian.

1. Identify the list of spaces you need to create

Spaces are like folders, which allow you to organize your content by different categories.

We recommend creating a space per Team (i.e. Finance) or by Project (i.e. Software development).

2. Take the time to define your page structure

In each space, it is important to set up a clear and organized page structure so content is grouped by subject and relevance. You can use page hierarchy to group several pages under one single parent page. For example:

Page tree in Confluence

When you have several levels of hierarchy, it might be useful to use the Children Display macro on parent pages. This way, users won’t have to expand the whole tree to find their page.

3. Use page templates

Confluence comes with a set of page templates, also called Blueprints, that allow you to:

  • Group pages by category of content (i.e. How To articles, Meeting Notes, etc.).
  • Have a standard layout and structure for those pages.
  • Save your employees’ time, as they aren’t recreating the wheel with each page.

Confluence gives you the flexibility to set up your own templates and promote them to users, so they’ll have easy access to the pages. We recommend using the Create from Template macro, on your home page space, and also train users on the details for each available template.

Quick Tip 

You can also structure your content as training materials for onboarding or internal education.

Click here to learn how!

4. Increase productivity by using Confluence macros

Confluence comes with a set of useful macros that provide a range of functionalities, which can make your pages more dynamic and customizable. This can enhance the look and feel of your pages while improving the user experience when browsing through content. A full list of macros bundled in Confluence can be found here. Alternatively, the Atlassian Marketplace offers a range of apps which can give you more choices for third party macros.

Confluence macros

5. Organize your attachments

Confluence makes it easy to attach files to your pages, however keep in mind the following best practices:

  • Make sure to name your attachments in a way that is meaningful to make it easy for users to browse through them.
  • When uploading and updating version of an attachment, make sure to not rename it. By using the same name, the attachment is replaced rather than duplicated.
  • Optionally, you can organize your attachments in folders so all your files can be viewed in a structured manner. This can be achieved by using the Smart Attachments for Confluence app.

6. Avoid redundant content

Redundant content can be hard to avoid, especially if you need the same content in more than one place within your wiki. However, by duplicating content, it makes it difficult to keep everything updated without it becoming a tedious task.

To avoid this scenario, you can use the Excerpt and Excerpt Include macros and embed sections of your pages into other pages.

7. Label your content

Labels are an easy way to group pages and attachments that are relevant to the same topic, making it easier for users to find what they need.

A good rule of thumb is to make sure to choose labels that are relevant and meaningful. When labels are used consistently, you can make use of handy macros such as Content by Label.

8. Grant permissions wisely

It’s true that too many cooks spoil the broth. If you have too many administrators, chances are they’ll configure Confluence for their own needs rather than taking into consideration a global view, and in effect too many configurations in different directions can lead to performance issues. Make sure to give users the exact permissions they need to perform their work, and minimize the number of system and space administrators to no more than five people.

9. Train Confluence users to adopt best practices

Confluence is very easy to use, which can be a double-edged sword – everyone can use Confluence, but over time everyone can also contribute to creating a disorganized wiki if users are not mindful of their actions.

It is crucial to invest in your Confluence users, and train them on why it is important they use the right page structure, add the right labels, use the right macros, etc. To nail down these basics, Valiantys offers a Confluence in Action User Training to get your entire team on the same page. Likewise it is also important Confluence administrators are trained, as they will be supporting users and making changes that affect the whole system. Valiantys’ Advanced Confluence Training gets your admins ready to manage their own instance in just one day.

For more information on training your team to implement best practices on Confluence – or even the rest of the Atlassian suite – refer to Valiantys’ comprehensive trainings.