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:
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.
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.
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.
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:
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.
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.
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.
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.
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:
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:
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.
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.
