29. 12. 2024 Fabrizio Dovesi Atlassian, Service Management

Let’s Repopulate the Community of “Pandas 🐼” Who are Happy with How Their Company Handles Documentation

This post offers a simple and pragmatic way to manage your company's knowledge base with an SaaS product like Confluence.

Why are we always here talking about the documentation problem?

The title of this post references the Panda, an endangered animal that has become a symbol of the WWF since its founding in 1961.
The panda was selected as a symbol due to its status as the only giant panda in the Western world at the time, which made it an ideal representative of endangered species. Additionally, the panda’s image evoked a sense of tenderness and sympathy, making it an appealing choice. Its black and white colors also made it an ideal symbol for use in black and white printing.

The rarity of this characteristic among mammals, coupled with its endangered status and the sense of tenderness it offers, made me think of a surreal analogy: that of people being able to manage and make their documentation usable in their companies, and being comfortable with the documentation available from other teams, BUs, Departments, etc.

It’s not necessary to provide any examples of this topic! At some point in our careers, we have probably all been exposed to the complexity, irrationality, and more or less total lack of knowledge base management in an organization.

Based on our experience as consultants, we’ve identified that the issue typically arises from a lack of planning and engineering at the knowledge base level. This is often due to an underestimation of the effort required at the project planning stage, with the subsequent creation and maintenance of the knowledge base then left to the discretion of the teams involved.

In light of the above, the following paragraphs will outline a few key strategies for preventing and even reversing poor knowledge management practices in your organization. As you’ll see, we’ll present a particularly pragmatic and concrete guideline on how to approach the topic of Knowledge Base management to ensure it’s well-organized, useful, and maintainable.

Key elements and steps for achieving the result

In order to achieve effective knowledge base management, it’s essential to ensure that certain key characteristics are present in the content (documents, guidelines, videos, etc.) that forms it. These key characteristics are as follows:

Simple, rapid, and intuitive to create
Simple, rapid, and intuitive to locate and utilize
Developed through a collaborative process involving multiple individuals
Periodically updated and reviewed
Measured on actual usage and utility

As previously stated, let’s now explore a simple and well-structured method for establishing a knowledge base, regardless of the target audience.

Step 1: Brainstorm some possible scenarios and decide which is best

From our experience, we’ve found that although it can be onerous and time-consuming, the most beneficial step in the later stages is to provide upstream engineering on the optimal structure for one’s documentation.

While it may be urgent to get started, creating documentation and designing its structure may not be the most appealing task in the world. However it’s crucial to find the strength and resources to complete it! Our recommendation is to design potential documentation structures from a “blank sheet” without constraints related to current solutions, such as team segregation or obsolete documentation.

Once you’ve identified the most suitable option, you should then compare it with the others and choose the one that’s the most scalable, sustainable to maintain, and easiest to navigate.

It’s essential to follow and, wherever possible, convert into a tangible result the key drivers that should be taken into account when drawing up the documentation structure on paper:

All the stakeholders have a clear understanding of the overarching structure of the documentation
Organized in a way that eliminates confusion and ambiguity regarding document access
The result must be designed in a way that allows for practical and sustainable maintenance

Once you have decided on the most appropriate general structure to align with these drivers, contextualizing it in the scope of documentation you want to manage, you can proceed to the next step.

Step 2: Define your labeling strategy

First, please take the structure design you prepared in step one and identify which pages are exclusively devoted to search or menu presentation, as opposed to the pages that contain the actual content.

The next step is to design labels, which are tags that can be applied to Confluence pages. These labels should be created and attached to mock-ups only on pages that contain KB articles (look at the red ones in the picture below).

Once the labels have been associated with the pages, it’s strongly recommended that an Excel file be generated to confirm that no duplicates have been created and to assist with the following steps.

This file will be helpful in the future for preventing duplicates when creating additional pages and spaces. So it’s essential to ensure that it is updated as you determine new sections of the documentation to be included in your knowledge base structure.

Step 3: Create your templates in Confluence

Templates in Confluence serve as “blueprint” pages, providing a foundation for creating new pages. These templates can be either global, applicable across all spaces, or tied to a specific space, available only within that designated boundaries.

A great feature of these templates is the ability to include predetermined default labels, which is a crucial aspect of the solution we’re proposing today.

In fact, the objective is to prepare a template for each page that will contain actual content. These templates can be blank and without structure/layout as a starting point. If you prefer to grant autonomy to the authors, or if you simply lack the time to define the main titles of the template document you’re preparing, this is not an issue! What is crucial, however, is to assign the predetermined labels to the individual templates produced.

Step 4: Create your page structure in Confluence

The final step in the process is to prepare the page structure previously outlined on paper and associate the newly created templates with the buttons that can be inserted into the Confluence pages via the “Create from template” macro.

Once saved, you can place your new button on the desired page and in the preferred position. We recommend specifying a message for users to place near the button. This message should explain that the button is intended for creating new articles on the specified topic, and they should avoid using the standard “Create” button at the top or other “+” buttons found into the side menu.

One Last Recommendation

To enhance your solution, you may wish to explore the additional useful elements found in Confluence, in particular we recommend exploring the functionality of Confluence automation. This is an excellent way to ensure that documentation remains user-friendly, easily accessible, well-organized, and well-managed.

To better understand the range of possibilities, please refer to the following examples from the Confluence Automation Library.

Conclusions

It’s essential for organizations to implement effective documentation processes to avoid issues related to inadequate Knowledge bases, or the lack of documentation practices. This blog post offers a pragmatic approach to defining a KB, utilizing Confluence as the central platform.

However, it’s important to note that there are various methods and tools available to assist in managing this process within your company or team. The advent of AI offers a promising outlook for addressing this issue, making it less “painful” for companies worldwide in the future.

For those who feel they are not properly managing their documentation, it’s essential to act promptly. Any knowledge or information that is not documented (or recorded on audio, video, etc.) will eventually be lost. Therefore it’s crucial to prioritize this task by allocating the necessary time and budget immediately. Only then will you be able to create the ideal environment for repopulating your Pandas community “who are happy with how their company handles documentation”.

These Solutions are Engineered by Humans

Did you find this article interesting? Does it match your skill set? Our customers often present us with problems that need customized solutions. In fact, we’re currently hiring for roles just like this and others here at Würth Phoenix.