What actually belongs in a codebase wiki

The usual story about internal documentation is that people won’t write it. I’ve watched enough of these die to think that’s the second problem, not the first.

The first is that nobody knows what to write. Someone creates the space, names it after the service, and then sits looking at an empty page trying to decide whether this is the place for the deploy runbook or whether the deploy runbook is its own thing, and whether either of those belongs near the API reference. Half an hour later there’s a page called “Overview” with four bullet points in it, and that’s where the initiative ends.

A blank wiki is a worse prompt than a blank page. At least a blank page has a subject.

The split that most wikis get wrong

Before any of the sections, there’s one decision that determines whether the rest lands: who is this for?

There are two readers, and they want opposite things. Someone working on the code wants to know where the seams are — how a request travels, why the queue is where it is, what breaks if they touch the adapter. Someone using what the code produces wants to know how to install it and what to do when it errors. Neither cares about the other’s pages.

Most internal wikis never make the call, so they end up serving both badly: architecture diagrams filed next to a getting-started guide, in an order that assumes you already know which half you’re in. That’s why wikipilot init opens with the question rather than a menu of templates. Technical, user guide, or both — and if it’s both, the two halves stay distinguishable instead of being interleaved by whoever wrote the page last.

The pages people using it need

Getting started. Install, run, see something happen. The test is that a stranger can follow it with your repo open in one window and nothing else, and it should be brutal about prerequisites — the step that gets skipped is always the environment one, and it’s always the step that breaks.

Guides. One page per task somebody actually performs, titled by the task. “Configuring SSO”, not “The auth subsystem”. If you can’t name the person who’d read it, it’s probably reference material wearing a guide’s clothes.

Then two sections that only work if you let reality write them. An FAQ drafted up front is a list of questions the author found interesting; a real one is what the support inbox and the Slack channel already say, transcribed — so if you haven’t shipped yet, leave it thin and let it fill. Troubleshooting is the same discipline applied to failure, with one extra rule: symptom first, cause second. People arrive there by pasting an error into a search box, which means the error string is the heading. Not “Database connectivity”. The actual text, in the actual format the process prints it.

The pages people building it need

Onboarding. Clean checkout to first merged change. This is the section everyone agrees is valuable and nobody writes, because the people who could write it stopped needing it eighteen months ago. That’s exactly why it has to be captured rather than remembered: the knowledge has a shelf life measured in how long since you last suffered.

How it works. The architecture, and — more useful than the architecture — the primary flow. One trace through the system, end to end, following a real request or a real job. Box diagrams tell you what exists. A flow tells you what happens, and it’s the thing a new engineer will re-read three times in their first month.

Technologies. A page per meaningful dependency, and here’s the part that makes it worth having: why this one. The version and the link are on npm already. What isn’t anywhere is that you picked it in 2023 over the obvious alternative for a reason, and that the reason may or may not still hold.

Reference is lookup material — commands, config keys, environment variables, endpoints. Nobody reads it; everybody searches it. Optimise for findable over readable and don’t let prose creep in.

Cookbook. Short, copy-pasteable recipes for the things people do repeatedly — reset the local database, regenerate the fixtures, run one test in isolation. This is the section that absorbs the tribal knowledge currently living in three people’s shell history.

And in front of all of it, one page — start here — that says what this project is and points at the right half of the wiki depending on why you arrived. It’s the only page you can assume gets read.

Order is a feature

Those ten sections are what --preset all drafts, and they come out in a deliberate sequence: the pages a newcomer needs first, then the ones you consult while working, then the ones you look things up in. wikipilot.config.json holds the list, and it’s authoritative — edit sections directly to add or reorder beyond what the preset gave you.

This matters more than it sounds. A wiki sorted alphabetically or by creation date is a filing cabinet. A wiki sorted by how far along the reader is, is a path. The second one gets finished, because each page implies the next.

The part I should be honest about

Two caveats, both real.

Ten sections on a four-hundred-line utility is absurd. The right structure for a CLI you wrote last Tuesday is not the right structure for a platform with six services, which is why --preset technical and --preset user-guide draft six sections and five rather than the full ten. Pick the smaller one and grow into it. An empty section is worse than a missing one — it reads as neglect rather than as scope.

And structure doesn’t write anything. A perfect skeleton with nothing in it is still a blank wiki; you’ve just organised the blankness. What structure does is remove the excuse, and remove the half-hour of deciding where things go, which is where most attempts stall. Something still has to fill the pages, and that’s the expensive step — the one where the docs-as-code approach earns its keep, because the pages sit in the repo next to the code they describe, get reviewed in the same pull request, and can be regenerated by something that reads both.

The section list is the cheap part. Take it, ignore the tool that produced it if you like, and at least you won’t spend your half-hour on the filing.