Blog Posts•Advanced Panelboxes for Confluence•Navitabs - Tabs for Confluence•Translations for Confluence•Viewtracker - Analytics for Confluence
How to Use Confluence for Documentation
Last updated on August 15, 2023
Note: The following text on documentation in Confluence originates from an article in K15t’s Rock the Docs. The text is modified and updated with information relevant to bitvoodoo.
We admit it: Documentation is not like a gripping novel that you read late into the night. Instead, it’s a crucial lifeline when questions arise, like: “And what do I have to do now?” Only if users get stuck or want to know more will they consult our documentation. In these cases, you want to ensure they get a quick answer instead of a long-winded explanation.
All the effort you put into your documentation is useless if your readers can’t find the right information. It’s especially important in a tool like Confluence, where pages can be inserted quickly, that your team consistently pays attention to your pages’ structure and naming.
When creating documentation in Confluence, you should keep these points in mind:
Understand how users search for information
Structure your content
Write for your user
This article covers Confluence documentation best practices and features provided by bitvoodoo apps to help in the process. Let’s delve into the key aspects to consider.
Understand how Confluence users search for information
Before you start writing, you should be aware that your users have plenty of ways to find the content they’re looking for. Each Confluence user has different searching habits and ways of navigating, but the more common approaches are using the page tree or Confluence’s built-in search.
🌳 Use the page tree (navigation)
Even with a search bar available, this is still what many users do: navigate through the space structure by interacting with the page tree on the left. It pays off to be consistent in your structure and naming conventions for this type of user. It allows those not keen on using the search bar to find the information they need.
🔎 Use Confluence’s quick and advanced search
Confluence’s search functionality is often the fastest way for users to find what they’re looking for. After typing in a specific search term, the user can narrow down the results by filtering for space, contributor, label or date.
If the results are still not satisfactory, here are some options to modify the search:
Exact match by putting a search term in quotation marks (“…”). Example: “Projects 2022” only shows results that appear in this exact spelling and order.
Wildcard: An asterisk (*) replaces one or more characters in a search term. Example: Project* will also show results such as Projects or Project plan
Search terms can be combined with “OR” or “AND”. Example: Projects AND 2022 displays all pages that contain both search terms. Projects OR 2022 displays all pages that contain one of the two search terms.
Certain words can be excluded by adding “NOT” or “-“. Example: Projects NOT 2022 only displays results that contain the word Projects, but not the term 2022.
🕵️♀️ Analyze searches
If you are using bitvoodoo’s app Viewtracker, you can quickly find the most frequent search terms and those that didn’t provide any results. Use this information to improve existing documentation in Confluence (e.g., rewrite page titles, create new labels) and to find topics for missing content.
Structure your Confluence documentation
While adding content to a Confluence page is easy, managing multiple ideas on one page can be challenging. If content gets too long, try not to squeeze everything onto one page. Rather, think of structuring your topic like an onion. First, give the reader a rough overview, then peel back each topic layer. The more clearly the content is presented, the easier it is for your users to find the right information.
One of the best practices to structure Confluence documentation is by creating child pages or linking to pages with specific labels.
🗂️ Use tabs to structure pages
A great way to add this structure is to get acquainted with the bitvoodoo app Navitabs for Confluence. Using the multiple macros in the app, you can create clickable tabs within your page. The tabs can be displayed horizontally or vertically. This allows your reader to access all information they need in structured chunks. They don’t even have to leave the page to do this, so there is no danger of losing them in the page tree navigation.
ℹ️ Insert colorful panel boxes for visual clarity
Help users find their way around a page by using panels. These can be the standard Confluence panels like info, tip, note and warning. Alternatively, you can use bitvoodoo app Advanced Panelboxes to create customized panels. For example, we use them in our documentation to structure the overview page of each app.
Write for your user
If you want your documentation in Confluence to be helpful for your audience, always keep your user’s goals and intentions in mind. Think of specific use cases and answer potential questions in advance.
As you write, you should also keep an eye on Confluence’s search parameters that will help users to find the information they’re looking for:
Title: Confluence checks how often the search term appears in the title.
Content: Confluence checks how often the search term appears in the content.
Document age: Newer Confluence pages will be ranked slightly higher.
Popularity: The more links and likes a page has, the higher it’ll rank in the search results
Write thoughtful page titles & headings
Well-structured spaces and pages are the basis for finding the right information, but clever page naming conventions help clarify your structure. Find unique and meaningful titles and subtitles, and stay consistent.
One of the Confluence documentation best practices is adding headings within your page’s body text. The headings help structure your content well. They should be precise and reader-friendly so that someone skim-reading can quickly find their way around. Once headings are in place, you should try to use the Table of Contents macro whenever possible. We often place it right below the page title and separate it with a horizontal line from the main content.
Or you could get creative and place the macro within an Advanced Panelbox macro with a specified title, like this:
🇩🇪 Add translations for your international audience
If your documentation is accessed from all over the world, consider adding translations. With the bitvoodoo app Translations for Confluence, you can add as many languages as you like to any page or blog post. On Data Center and Server, you can even translate the page title.
Of course, this extra translation effort only pays off for 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.
Having multilingual content on pages allows Confluence to find relevant terms and keywords in more than one language and display more relevant search results to international readers.
🗣️ Allow for interaction
Keep your Confluence pages updated and encourage readers to use the like and comment functionality (depending on their permissions). That proves to Confluence that your documentation is of good quality and also increases the popularity of your content within the search results.
Within the bitvoodoo app Viewtracker, you can see which content was commented on, liked, or watched by readers, among many other metrics.
Documentation is helpful when content is presented in a complete, clear and structured way. It helps to build up a common body of knowledge. Therefore, information must be easily accessible and quickly found.
While your bright mind is your best tool, using specialized apps eases the workload of any technical writer. A tool like Viewtracker also allows you to optimize your Confluence documentation based on real numbers. It saves you the hassle of guessing and making assumptions about where best to invest your valuable time.
Many bitvoodoo apps focus on needs specific to Confluence content creators and technical writers. Discover them all on the Atlassian Marketplace, and start your free trial today.