3 Items
Your Documentation Is Valuable – Help Users Find the Right Information
Steffen Burzlaff
Creating documentation for your team in Confluence is easy. But all the effort you put into your internal documentation is useless if your readers can't find the right information. It's especially important in a lightweight tool like Confluence where pages can be inserted quickly, that your team consistently pays attention to the structure and the naming of your pages.
Internal documentation can be anything such as product concepts, process documentations or meeting notes. Its purpose is to understand decisions, to avoid misunderstandings, and to explain guidelines. However, 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.
When creating documentation for your team, we recommend keeping these points in mind:
Understand how users search for and find information,
Structure your content,
Write for your user.
Understand How Users Search For and Find Information
Before you start writing you should be aware that your users have plenty of ways to find the content they're looking for. We have team members with different searching habits and ways of navigating our Confluence instance, so we want to share the more common approaches so you can prep your documentation in the right way:
Option 1: Use the navigation
Even with a search bar handy, this is still what a lot of users do: navigate through the space structure. This pays off if you're consistent in your structure and naming conventions so that so that those who aren't keen on using the search bar will find their way to the information they need.
Option 2: Use the Confluence dashboard
Confluence offers dashboards that provide an overview of recent activities and updates:
All updates: This is a list of all pages that have been updated recently in the organization.
Popular: This overview shows all pages that have been liked or commented recently.
Recently worked on: A user finds all pages they have been editing in the past few days or weeks.
Recently visited: This overview shows all pages someone visited and can be helpful when they forgot the name or path to a page.
Option 3: Use 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:
Option |
Example |
|---|---|
Exact match by putting a search term in quotation marks ("..."). |
"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. |
Project* will also show results such as Projects or Projectplan |
Search terms can be combined with "OR" or "AND". |
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 "-". |
Projects NOT 2021 only displays results that contain the word Projects, but not the term 2020. |
Structure Your Content
If you use Confluence, your team probably documents all of their work there. At K15t, we collaborate on our internal documentation using Confluence; it's at the heart of everything we do. The structure within Confluence happens on different levels: spaces and pages. This is an example of a page tree in our demo help center:
At K15t, we have spaces for teams, projects, and internal organization where we create documentation such as product specifications, marketing plans, technical instructions or employee handbooks. Keep in mind that every piece of documentation has its own goal and audience. The structure you choose for your content will have a big impact on writers and users.
We've outlined the steps you should take to ensure that you create a documentation structure that works for the whole team. Find a structure that works for your organization or product and stay consistent.
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, structure your thoughts by creating child pages. This way you can keep your page tree clear and simple to navigate and everyone knows where each piece of content belongs.
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 content is presented, the easier it is for your users to find the right information.
Write for Your User
You can do more than improve the overall structure of your documentation. If you want your documentation to be helpful for your audience, keep your user's goals and intentions top-of-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
Well-structured spaces and pages are the basis of finding the right information, but clever page naming conventions really help to give your structure clarity. Find unique and meaningful titles and subtitles and stay consistent.
For internal documentation at K15t, we find the YYMM structure works well e.g. 2105 Marketing Webinar, but perhaps your team has a structure that fits better. Here are some tips on page naming conventions for better searchability in confluence.
Adding headings within the body text of your page help to structure your content. They should be precise and reader-friendly, so that someone skim-reading can quickly find their way around.
Stay consistent with your wording
Optimize for search wherever you can by choosing the right terms and keywords to make documentation findable for your users. Stay consistent with your expressions as Confluence checks how many times a word shows up within a page. The more the keyword appears, the higher your page will rank in Confluence's search results.
At K15t, if we create a "product roadmap", we stick to that term and don't switch to "product plan" or "product timeline". A tool like Scroll Content Quality for Confluence Cloud can help you to do that. You can define custom rules that check Confluence pages for spelling, terminology, capitalization, macro usage, and more.
Keep your pages up to date and encourage your team to use the like and comment functionality. That proves to Confluence that your documentation is good quality and also increases the popularity of your content within the search results.
Better Structure, Right Information
Documentation is helpful when content can be stored 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.
At K15t, we rely on our documentation in Confluence. It is our source of truth that helps us become better as a team and we all feel responsible for it.
