Building a QA knowledge base people actually open

Every QA team has been here. Someone spends a week writing beautiful documentation. Six months later, a new tester follows it, and half the steps are wrong — the URLs changed, the test accounts were deleted, the feature was redesigned. The new tester learns the real lesson: do not trust the wiki, ask a human.

From that moment the knowledge base is dead, no matter how many pages it has.

The problem is never writing documentation. Teams write plenty. The problem is that documentation decays the moment the product moves, and most knowledge bases have no defence against decay. This guide is about building one that does.

Short version

Document the stable, link to the changing.
Every page gets an owner and a review date, or it gets deleted.
Small and true beats large and doubtful — aggressively delete.
The wiki holds knowledge; tickets hold events. Do not mix them.
Measure success by one thing: do people check the wiki before asking?

What belongs in a QA knowledge base

The test that decides everything: how fast does this information change?

Changes rarely — write it	Changes constantly — link it, or leave it in the system that owns it
How to set up a test environment	Current bug list (lives in the tracker)
Test account conventions and where credentials live	Feature specs (live with product docs)
The team's bug report format and severity scale	Test run results (live in the test tool)
Known fragile areas and their history	Current sprint scope (lives on the board)
Domain knowledge: what "settlement" means here, why refunds work strangely	Individual test cases for fast-moving features
How-to guides: capturing HAR files, device logs, flags
The release sign-off template and past sign-offs

Writing fast-changing content into wiki pages is how graveyards form. The wiki should describe the rules of the world, not the current state of it — state belongs in the systems that track it, one click away.

A structure that survives

Deep hierarchies die because nobody agrees where things go, so pages get lost and duplicated. Keep it to two levels and few sections:

QA Home
├── Start Here          (onboarding path, reading order — one page)
├── How We Work         (bug format, severity scale, DoD, sign-off template)
├── Environments        (URLs, test accounts, flags, seeding data)
├── How-To Guides       (HAR capture, device logs, bisect, throttling…)
├── Product Knowledge   (one page per domain area: payments, exports…)
└── Fragile Areas       (the hotspot list: what breaks, its history)

Two pages here do the most work per word:

Start Here exists so that a new tester's first day has an ordered path — five links, in reading order, ending with "make your first bug report". Onboarding is the moment documentation earns or loses trust for good.

Fragile Areas is the page nobody else will write: the living map of where the product breaks. Exports lose column order after the 4.2 refactor; timezone handling has bitten us three times; the checkout retry logic is subtle — see BUG-1204, BUG-1187. This is the institutional memory that walks out of the door when a senior tester leaves. Write it down while they are still in the room.

Ownership, or why "everyone's wiki" is no one's

A page without an owner is already decaying — nobody feels the responsibility, so everybody assumes someone else updated it.

The rule that works: every page carries a name and a review date in a header.

Owner: Sana · Last reviewed: May 2026 · Review by: Nov 2026

Two small ceremonies keep it honest:

A quarterly review hour. The team splits the pages past their review date. Each page gets one of three outcomes: still true (bump the date), fix it (fifteen minutes, now), or delete it. Most teams need one hour per quarter. That is the entire maintenance budget of a living wiki.
Touched-it-fix-it. Whoever discovers a wrong step fixes it on the spot — not files a note about it. Editing must be low-friction enough that the fix is faster than the complaint.

And deletion deserves its defence: an outdated page is worse than no page, because no page sends the reader to a human, while a wrong page sends them confidently in the wrong direction. Deleting is not losing knowledge; version history keeps everything. It is removing traps.

The wiki–ticket boundary

A knowledge base rots fastest when it starts absorbing things that belong in tickets: investigation notes, one-off findings, bug detail.

Keep the boundary crisp:

Tickets record events. This bug, on this build, with this evidence. Rich detail belongs there — steps, screenshots, console output, network logs. With a capture tool like Crosscheck, that evidence attaches itself, which keeps tickets self-contained and the wiki free of pasted stack traces.
The wiki records patterns. When three tickets rhyme, that is a wiki entry in Fragile Areas — three lines and three links, not three copied tickets.

The knowledge base should link to tickets constantly, and contain them never.

Making people open it

The habits that actually move the needle:

Answer questions with links. When someone asks something the wiki covers, answer with the link — kindly, and after fixing the page if it was hard to find. This trains both sides: askers learn the wiki answers questions; owners learn where findability fails.

Put the wiki where the work is. Link "How We Work" from the bug tracker's template. Link environment pages from the CI job. Documentation that must be sought will not be; documentation that appears in the path gets read.

Watch the real metric. Page counts and edit counts flatter. The only measure that matters: when a new person joins, do they get their answers from the wiki or from interrupting a senior? Track your onboarding questions for one hire — every question the wiki failed to answer is your backlog, in priority order.

Frequently asked questions

Which tool should we use? Whichever your company already uses for other documentation — Confluence, Notion, a docs folder in the repo. Adjacency beats features: a great tool nobody visits loses to a mediocre one on the path everyone already walks.

How much time does maintenance really take? With ownership headers and the quarterly hour: about one hour per person per quarter, plus seconds-long fixes as people touch pages. Without them: infinite, because the wiki gets rewritten from scratch every two years.

Should test cases live in the knowledge base? Stable, slow-moving checklists (release smoke, launch checklist) — yes. Detailed per-feature cases — no; they belong in a test management tool or alongside the code, where they can change with it.

How do we start when there is nothing? Do not schedule a documentation sprint; it produces a large dead wiki in one motion. Instead, write each page the first time someone asks for its contents. Six months of ask-driven writing produces a small wiki where every page has a proven audience.

What about documenting for auditors or compliance? Keep compliance artefacts in their own clearly-labelled section with their own retention rules. Mixing audit paperwork into working documentation makes both worse — one gets padded, the other gets ignored.