Skip to content
Rivl
13 November 2026Internal tools10 min

An internal knowledge base for staff, and what makes it work

Somebody answers the same question in chat for the fourth time this month, so the team agrees to write things down. Six weeks later there are ninety pages and people still ask in chat. The failure is predictable and it is not the tool.

The trigger is always the same. A new person asks how the refund process works. Someone answers in chat, properly, with the edge cases. Two weeks later somebody else asks it again, and the answer has to be rebuilt from memory because the original is four hundred messages up.

So the team builds a knowledge base. Ninety pages go in over a fortnight, enthusiasm included. Then the refund process changes, two pages are updated and five are not, and within a quarter the most reliable way to get a correct answer is still to ask the one person who knows. The pages are now worse than nothing, because they are wrong with authority.

That outcome is not a tooling problem. Every tool in this category can hold text and search it. The problems are findability and decay, in that order, and almost nothing written about internal wikis addresses either one.

The sections of this note in order: what a knowledge base is narrowly for, what the DORA research measured about documentation quality, why findability fails before content does, the structure that survives a busy team, keeping it current, where it connects to what you already run, and when not to build one.
How this note is organised.

What it is for, stated narrowly

A knowledge base that tries to hold everything the company knows will hold nothing anyone can find. The useful version has a narrower job: it answers questions that get asked more than once and whose answer is the same every time.

That definition excludes a lot, deliberately. It excludes decisions, which belong in whatever tool records decisions. It excludes anything in flight, because a page about work in progress is out of date before it is read. It excludes training material, which is a different artifact with a different reader, and it excludes the things one person does once a year, which are better captured as a checklist attached to the task than as a page nobody will think to search for.

What is left is smaller than teams expect. Processes with steps, policies with a yes or no answer, and the twenty or thirty questions a new joiner asks in month one. That list is a day of work and it covers most of the chat traffic the team wants to end.

Documentation quality is measurable, and the effect is not small

The best evidence here is not about wikis in general. It is DORA's work on documentation quality, from the 2022 State of DevOps Report, which assessed documentation on eight metrics covering what it calls clarity, findability and reliability. Those three words are worth keeping, because they are the axes on which internal documentation actually fails.

The finding is that documentation quality is not a nice-to-have running alongside technical practice. It changes how much that practice is worth. DORA reports the lift to organisational performance from each capability it studied, split by whether the team had below-average or above-average documentation quality, and the gap between the two columns is the point.

CapabilityLift, below-average docsLift, above-average docs
Trunk based development36%1525%
Continuous integration34%750%
Continuous delivery63%656%
Supply chain security37%451%
Site reliability engineering79%343%
Loosely coupled teams46%313%
Version control27%278%
DORA's published figures for the lift to organisational performance from each technical capability, compared between teams with below-average and above-average documentation quality.
The same practice, documented well or documented badly. The figures are DORA’s, from the 2022 report.

Read those as DORA states them: the lift from a capability, amplified by documentation quality. They are survey results from software delivery teams, not an experiment, and not a promise about your refund process page. The transferable part is the ranking of what matters. DORA did not find that teams needed more documentation. It found that quality, and specifically findability and reliability, decided whether the documentation did anything at all.

DORA's own advice on improving it is unglamorous and points outward: use documentation guidelines, and work with technical writers or documentation champions where they exist. It also points at Google's developer documentation style guide, which is free and more useful to a non-writer than its name suggests. Two of its rules carry straight into an internal wiki: "Use shorter sentences. Try to use fewer than 26 words per sentence", and "Don't use color, size, location, or other visual cues as the primary way of communicating information". A process page that depends on a screenshot's red arrow stops working the moment the interface changes.

Findability fails before the content does

Ask why they asked in chat instead of searching, and the answer is rarely that the page does not exist. They did not know what it would be called, searched the obvious word, got eleven results and could not tell which was current.

Three habits fix most of that, and none of them is a feature you buy.

  • Title pages as the question, not the topic. "How do I issue a refund" beats "Refund policy", because the former is what someone types.
  • One page per question, with an answer in the first two lines. If the answer needs context, the context goes below the answer. Readers who have to scroll to find out whether they are in the right place leave.
  • A single owner named on every page, and a last-reviewed date next to it. Not last-edited, which a typo fix resets, but last-reviewed by a human who confirmed it is still true.

The owner and the review date are what make it trustworthy, and trust is the whole asset. A reader burned once by a stale page treats every page as suspect afterwards, and the wiki reverts to decoration while the chat traffic continues.

Keeping it current, which is the actual problem

Every knowledge base decays, because the world it describes moves and the pages do not. DORA is direct about the cost of this: documentation "needs to be actively created and maintained, which takes work". There is no version of this where the writing is a one-off project.

The mechanism that works is not a quarterly audit, because quarterly audits get skipped the first time anyone is busy. It is to attach the update to the change. Whoever changes the refund process owns the refund page that day, as part of the change rather than as follow-up. That is a small rule with one hard requirement: the page has to be short enough that updating it is a five minute job. Long pages do not get updated, they get abandoned, which is a good argument for keeping each one narrow.

The second mechanism is to delete. Ninety pages of which thirty are stale is less useful than forty that are all true, and deleting is the cheapest quality improvement available.

Where this connects to what you already run

If what you have today is a folder of documents and a long-running chat thread, the honest prior question is whether this needs software at all, which is the subject of internal tools for a small business, and when to stop using Excel. For a knowledge base specifically the answer is usually no custom build: an off-the-shelf wiki is genuinely fine, and the work is editorial rather than technical.

The place it does become a build is when the knowledge base starts feeding something else. If you are planning to put an assistant in front of it, the quality of the pages becomes the quality of the answers, and the failure modes are specific: how to stop an AI chatbot giving wrong answers is the companion piece, and the short version is that a confident answer drawn from a stale page is the worst outcome of the two.

The adjacent case is onboarding, where most of these questions originate. A first-month checklist and a knowledge base solve different halves of the same problem, and the split is described in an internal tool for employee onboarding, scoped to day one. Training organisations hit the same wall from another direction, usually in spreadsheets, as in the three tools every training centre rebuilds in spreadsheets.

One more parallel, from outside software. A CRM is a sales team's knowledge base, it decays for exactly these reasons, and the consequences are easier to price because they show up in a forecast. BDG Labs set out six maintenance rules that survive a busy quarter in CRM hygiene for small sales teams, and the rules are recognisably the same ones: one owner, short records, and deleting what is dead.

When not to build one

Two cases. If the team is three people in one room, the knowledge base is overhead and the chat thread is genuinely fine. Write down the five things that would hurt if the one person who knows them were away, and stop there.

And if the questions keep coming because the process itself is unclear, documentation will not help. Writing down a confusing process produces a confusing page, and the repeated question is a symptom worth listening to rather than a gap to be filled. Fix the process, then write one short page about the result.

The honest limits

DORA studies software delivery organisations. Its documentation metrics are about technical documentation read by engineers, and the capabilities in that table are engineering practices. A staff knowledge base covering refunds and holiday policy is a different artifact with a different reader, and we are borrowing the finding about findability and reliability across that gap. We think the borrowing holds, because the failure modes it names are the ones we see in every internal wiki, but it is a borrowing and the figures above are not about your wiki.

There is also no number here for how much time a knowledge base saves. We could repeat one of the figures in circulation about hours lost searching for information, and we are not going to, because the ones we checked trace back to vendor surveys with no published method. Count the repeated questions in your own chat for two weeks instead. That number is small, specific and yours, and it is the only one that should decide whether this is worth doing.

Describe it. We build it.

Seven or twelve days, pay on delivery, a year of maintenance included. Bring the problem, not a spec.

Book a meeting

Read next