Choosing a Knowledge Base and Getting People to Use It

Every organisation has a wiki. Most are distrusted, out of date and searched only after asking a colleague first.

The tool is rarely the cause.

The three failures

Nobody trusts it. A page with no date and no owner might describe how things worked three years ago. Faced with uncertainty, people ask a person instead, which is precisely the interruption the wiki was meant to prevent.

Search does not work. In a distributed team you spend more time finding things than writing them. If search returns forty results ordered badly, people stop searching.

Writing is nobody's job. Documentation happens in the time that does not exist, so it happens when someone is annoyed enough about being asked the same question repeatedly.

Fix these three and most tools are adequate. Fix none and no tool helps.

Selection criteria that matter

Search quality, tested on your own content before committing. Ask a question you know the answer to and see whether the tool finds it.

Ease of editing. Anything requiring more than about thirty seconds of friction to fix a wrong line means wrong lines stay.

Page-level ownership and dates, visible to readers.

Export. Ask how the content comes out before putting it in.

Integration with where people already work. A knowledge base nobody visits is a knowledge base nobody reads. If links to it appear naturally in chat and tickets, it becomes part of the flow.

Structure that survives

Shallow. Deep hierarchies are maintained by nobody and navigated by no one. Two levels is usually enough; people find things by search regardless.

Organised by question, not by department. Readers arrive with "how do I request access", not "let me browse the IT section".

One page per thing. Splitting a topic across five pages guarantees four go stale.

A visible index of the twenty pages that matter. Most reading concentrates on a small number of pages. Make them findable without search.

Making it trustworthy

Date and owner on every page, displayed to the reader. This single change does more than any reorganisation, because it lets a reader calibrate.

Review cycle for the important pages. A quarterly check on the twenty that matter, not an annual audit of everything, which never happens.

Archive aggressively. Move anything untouched and undefended for a year out of the main space. The instinct to keep everything is what creates the pile nobody trusts.

Fix on discovery. A norm that anyone who finds an error corrects it, immediately, without permission. This requires low edit friction and explicit permission, both of which have to be stated.

Getting it written

Part of the task, not after it. A change is not complete until the page reflects it. This is the only mechanism that works reliably.

New joiners fix what confused them. The highest-yield documentation practice available. They are the only people who can see the gaps, and the window is about a month.

Answer questions with a link. When someone asks something answered on a page, send the link. When it is not answered anywhere, write the page and then send the link. Slower once, faster forever.

Owners for areas, not for the wiki. "The wiki" belonging to everyone means it belongs to nobody.

What not to do

Do not migrate to a new tool to fix a content problem. Migration is expensive, and the stale content arrives in the new tool intact.

Do not mandate documentation without removing something else. It is work, and work added without capacity does not happen.

Do not let two systems coexist. Two homes for documentation means neither is trusted and both are searched.