Best practices for maintaining a knowledge base

In our main guide on what knowledge bases are, we explored the fundamental role these tools play in organizing information for teams and individuals. However, simply having a knowledge base is not enough. To truly be a valuable tool in organizing and serving information, it requires a lot of intention, care, and a commitment to maintain. A neglected knowledge base quickly becomes a graveyard of outdated procedures and duplicate data, making it less valuable and in some cases more damaging than valuable.

Best practices

In this article, we outline some of the most essential practices for keeping a knowledge base up-to-date and reliable. Most of these recommendations are directed mostly at team-wide company bases but may also benefit personal knowledge bases.

Establish clear ownership

One of the most common reasons that knowledge bases fail is when a team fails to assign certain responsibility. In many cases, the knowledge base is considered everyone's responsibility - but as the "tragedy of the commons" concept dictates; when everyone is responsible, no one is responsible.

Assigning specific people to different sections of a knowledge base helps ensure accountability and responsibility. This doesn't mean that it should be that person's only role in the company or team, but should rather be someone that is already involved with that topic - for example, a senior developer could be the one to ensure that technical documentation is up-to-date. It should also not be this person's responsibility to write every word, but they should be in charge of reviewing content accuracy and ensuring that new information is updated accordingly.

It is important to note that just because there are clear owners of different sections, it doesn't mean that non-owners does not have accountability to the knowledge base. If someone for example searches up the wiki for some information and doesn't find it - or finds outdated information - it is just as much their responsibility to report it promptly to the stakeholder as it is for the owner to keep it up-to-date.

Make documentation part of the workflow

Keeping a knowledge base up-to-date depends largely on how it is involved in the workflow of the team. If documentation is considered a second-hand thing that gets done when "time is right", it will slowly rot away. rather, making it a part of the established workflow, whether it be iterative sprints or project milestones, ensures that information is added to the knowledge base while it's still fresh and prevents the memory loss that often occurs when teams wait until the very end of a project to document their findings or results.

An example of this could be that software teams should update documentation before a pull request is merged. Having documentation be part of the definition of "done" helps organically maintain the knowledge base rather than keeping it an afterthought.

Standardize structure and style

It is important to establish clear conventions for how information should be conveyed in the knowledge base. This both helps keep the information consistent across teams and stakeholders, but also reduces a lot of cognitive load for the people writing the documentation. If you are still deciding on your taxonomy and hub pages, this guide to structuring a knowledge base is a good starting point. Additionally, a rigid format can help search tools and large language models (LLMs) better scan and predict the information.

To accommodate this, consider keeping a library of templates for common document types, eg. "how-to" guides, troubleshooting articles or policy definitions. This makes it easy for team members to fill out and keeps the knowledge base homogeneous.

It is also important to have a concise document that covers basics such as heading hierarchy, tone of voice and how to interlink related resources.

Regular auditing

Despite integrating documentation into the established workflow, it is inevitable that the knowledge base suffer from decay over time. It could be a screenshot showing a user interface that has since been redesigned or a temporary workaround for a bug that has since been patched.

Scheduling regular auditing sessions where owners review their sections for accuracy can significantly help keep knowledge bases up-to-date and polished. As mentioned earlier, an outdated and unkept information library can at times be more damaging than beneficial, so having monthly or quarterly reviews can be very valuable.

This is even more important in an age where LLMs are an inherit part of writing documentation. As much as artificial intelligence can help speed up and maintain knowledge bases, there is still a margin for error, such as when LLMs "hallucinate" by making up false assumptions. If this is not caught during writing or auditing, it can significantly hurt trust in the knowledge base.

Build a feedback loop

The people consuming the information are often the best judges of its quality. If a support agent finds a help article unclear, or a new hire gets stuck on an onboarding step, there should be a easy way for them to report the issue.

Enabling comments or suggestion features that allow users or stakeholders to report errors or ask for clarification directly within the document can significantly help keep information reliable and up to date. This feedback should be treated as high-priority tasks, as they reflect real-world usage of the knowledge base. Also, when users see that their input leads to immediate improvements, they become active participants in maintaining knowledge base.

Conclusion

Maintaining a knowledge base is not a one-time project but an ongoing commitment to a team or product's success. By establishing clear ownership, integrating documentation into daily workflows, and fostering a culture of feedback, teams can transform a static library of information into a living, organic asset. It may be that the initial setup requires more effect, but the long-term reward of increased efficiency and trust will far outweigh the cost of maintenance if done right.