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.
Documentation is not like a thrilling novel that you read late into the night. In most cases, only when questions arise, like: “And what do I have to do now?”, will users seek out 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 the structure and the naming of your pages.
When creating documentation, you should keep these points in mind:
This article covers many best practices and features provided by bitvoodoo apps to help in the process.
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 content (e.g. rewrite page titles, create new labels) and to find topics for missing content.
It is easy to add content to a Confluence page, but managing multiple thoughts on a single page can sometimes 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.
A common way to structure topics in Confluence is by creating child pages or linking to pages with specific labels.
A great way to add this structure is to get acquainted with our 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 our 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 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.
Adding headings within your page’s body text helps structure your content. 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 our 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 our Viewtracker app or the built-in analytics in Cloud, you can quickly find the most important pages and translate those 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 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 our Viewtracker app, you can actually see which content was commented on, liked, or watched by readers.
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 content 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.
