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 make sure 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:
- Understand how users search for information
- Structure your content
- Write for your user
This article covers many best practices and features proven bitvoodoo apps to help in the process.
Understand how 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 a lot of 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 who aren’t 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 a user 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 2021” 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 2021 displays all pages that contain both search terms. Projects OR 2021 displays all pages that contain one of the two search terms.
- Certain words can be excluded by adding “NOT” or “-“.
Example: Projects NOT 2021 only displays results that contain the word Projects, but not the term 2020.
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 (eg. rewrite page titles, create new labels) and to find topics for missing content.
Structure your content
It is easy to add content to a Confluence page, but it can sometimes be challenging to manage multiple thoughts on a single page. If content starts to get 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 layer of the topic. 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.
Use tabs to structure pages
A great way to add this structure is getting 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.
Insert colourful 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 our app Advanced Panelboxes to create customised panels. For example, we use them on our documentation to structure the overview page of each app.
Write for your user
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:
- 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 of finding the right information, but clever page naming conventions help to give your structure clarity. Find unique and meaningful titles and subtitles and stay consistent.
Adding headings within the body text of your page helps to 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:
Add translation for international audience
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 a lot of 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.
Allow for interaction
Keep your pages up to date 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 specialised apps eases the workload of any technical writer. A tool like Viewtracker also allows you to optimise your content based on real numbers. It saves you the hassle of having to guess 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.