We admit it: Documentation is not like a gripping novel you read late into the night. Instead, it’s a crucial resource when questions arise, such as: “What do I have to do now?” Users generally consult documentation only when they are stuck or wish to learn more. In those moments, you want to ensure they find a quick answer rather than a long-winded explanation.
Your efforts in creating documentation will be ineffective if your readers cannot find the right information. This is especially important in a tool like Confluence, where pages can be quickly added. Your team needs to maintain consistency in the structure and naming of your pages.
When creating documentation in Confluence, remember these points:
This article will cover essential best practices for Confluence documentation and highlight features provided by bitvoodoo apps to streamline this process. Let’s delve into the key aspects to consider.
Before you start writing, you should know that your users have plenty of ways to find the content they’re looking for. Each Confluence user has different search habits, but common approaches include using the page tree or Confluence’s built-in search.
Even with a search bar available, many users prefer navigating through the structure using the page tree on the left. Consistency in your structure and naming conventions is beneficial for this type of user, as it allows those who may not be familiar with the search functions to locate the information they need easily.
Confluence’s search functionality often provides the fastest way for users to find what they’re looking for. After entering a specific search term, users can narrow down the results by filtering for space, contributor, label, or date.
If the results are still unsatisfactory, here are some options to modify the search:
Atlassian Intelligence transforms the Confluence search into an even more powerful knowledge search tool. You can enter your questions in full sentences and receive an answer in natural language, including the Confluence page from which the answers originate.
If you use bitvoodoo’s app Viewtracker, you can quickly find the most frequent search terms and those that returned no results. Use this data to improve your existing documentation in Confluence (e.g., rewrite page titles, create new labels) and identify topics that need coverage.
While adding content to a Confluence page is simple, managing multiple ideas on one page can be challenging. Avoid cramming too much information onto one page. Instead, think of structuring your topic like an onion—start with a general overview and delve deeper into each topic layer. A clear presentation of information will make it easier for your users to find what they need.
One of the best practices for structuring Confluence documentation is to create sub-pages or link to pages with specific labels.
A useful tool for adding structure in Confluence is the bitvoodoo app Navitabs, which enables the creation of clickable tabs displayed either horizontally or vertically. Using the macro “Tab Wizard,” you can create tabs from existing pages, pages with labels, and frames or by typing in your content. This helps you to present information in well-organized chunks, allowing readers to access all necessary content without leaving the page. Additionally, Navitabs’ tab design options in Cloud and Data Center make your page visually appealing.
Help users navigate your page using panels, like standard Confluence panels (info, tip, note, warning) or customized panels with the bitvoodoo app Advanced Panelboxes. These can enhance clarity for users, especially on overview pages.
To ensure your Confluence documentation meets the needs of your audience, always consider their goals and intentions. Think about specific use cases and proactively address potential questions.
Pay attention to Confluence’s search parameters that influence how easily users can locate information:
Popularity: Pages with more links and likes rank higher in search results.
Well-structured spaces and pages are essential for information retrieval, but clever naming conventions clarify your organization. Craft unique and meaningful titles and subtitles consistently. Utilize headings within your content for better structure, making it easy for readers to navigate. Incorporating a Table of Contents macro can also enhance usability.
Or you could get creative and place the macro within an Advanced Panelbox macro with a specified title, like this:
If your documentation caters to a global audience, consider offering translations. With the bitvoodoo app Translations for Confluence, you can add numerous languages to any page. This is particularly beneficial for pages with high traffic, allowing you to prioritize translations using analytics tools to identify the most important pages first.
In order to efficiently translate your content, we suggest using Atlassian Intelligence. Combining it with Translations for Confluence accelerates the translation process. Translations are generated in seconds, while AI-driven suggestions enhance content quality by exploring diverse phrasings and perspectives. It’s crucial to prioritize the job and translate first the pages with many views and/or interactions. Using tools like the bitvoodoo app Viewtracker or the built-in analytics in Confluence Cloud, you can quickly establish and translate the most important pages first.
Multilingual content on pages allows Confluence to find relevant terms and keywords in multiple languages and display more relevant search results to international readers.
Effective documentation is the cornerstone of successful knowledge sharing. By combining clarity, comprehensiveness, and organization, you create a valuable resource accessible to all.
Discover how bitvoodoo’s suite of apps specifically tailored for Confluence can elevate your content creation and management processes.
Start your free trial on the Atlassian Marketplace today and experience the difference firsthand.
