Documentation Is a Product With Users

Every team I have worked in has had a documentation problem, and every one of them described it the same way: "we should write more things down." That framing is why it never gets fixed. It treats documentation as a writing problem, and the writing was never the expensive part.

The economics nobody accounts for

Writing a page costs an afternoon. Owning it costs the rest of its life.

Every page you add joins a set somebody has to keep true, and the bill lands on readers rather than on the author. A stale page does not sit quietly in a corner waiting to be noticed. It surfaces in search, it reads as authoritative, and it charges every future reader the time it takes to work out whether to believe it. Accumulate enough of those and you have built something with a worse hit rate than asking a colleague, which is exactly what people quietly go back to doing.

That is the trap inside "write more things down." Volume is the easy half, and it makes the hard half worse. A documentation set can double in size and halve in usefulness in the same quarter.

The uncomfortable implication is that a page you are not willing to maintain is a net negative. Not neutral. Negative.

Why wikis in particular fail

The wiki is the default answer, and it is a large part of why the problem persists.

Anyone can add. Nobody owns the whole. There is no editorial standard, because the premise of the tool is that standards are friction. Search treats a page from three years ago exactly like the one written this morning. Over time the thing accumulates into something with no shape, and the collective response is never to fix it. People route around it instead, asking in chat and getting an answer that then goes unwritten, because everyone has learned that the wiki is where writing goes to be lost.

Every wiki I have watched die was killed by the same thing. It was nobody's product. It had contributors and no owner, and contributors add while owners cut.

A definition of done for a document

Product teams will argue for an hour about the definition of done for a feature and accept literally anything for documentation. The bar does not need to be high. Four questions get you most of the way:

• Who is this for? Not "the team." A specific person in a specific situation.
• What do they do after reading it? If there is no next action, you have written a memo.
• Who owns it? A name. A page with no owner has already been abandoned, it just does not know it yet.
• When is it checked again? A date. Documents never announce that they have gone stale.

Add a fifth for anything factual: exactly one page is allowed to state it, and everything else links there. A second copy is where drift starts, and once two versions disagree your readers are choosing between them at random.

None of that needs tooling. It needs somebody deciding that pages are not free.

Onboarding is the honest test

You can argue forever about whether documentation is good. You cannot argue with how long it takes a new person to become useful.

Time to usefulness is the one documentation metric I have found that resists wishful thinking, and it is worth measuring properly rather than by feel. When I built a product documentation framework at mrge around these ideas, that number came down by 83%, and it was not because we had written more.

It also exposes a cost that normally stays hidden. Onboarding is never paid by the person being onboarded. It is paid by everyone they interrupt, in fragments, and it lands in delivery velocity rather than in anything labeled onboarding, so nobody attributes it correctly and nobody funds the fix.

There is a cheap diagnostic here. Give a new joiner a real task in their first week and watch where they get stuck. Every question they have to ask a human is a gap with an address attached. That is a documentation backlog ranked by real demand, which beats any audit of what has gone stale.

Cut more than you add

The instinct is always to add, because adding feels productive and offends nobody.

Deletion is the higher-value work and almost nobody schedules it. Anything nobody has opened in a year is a candidate. Anything describing a system that has since been replaced is not history, it is a trap laid for the next person who searches. Prune on a cadence, the way you would groom a backlog, and say out loud that you are doing it, so that removing someone's page stops reading as a verdict on them.

A smaller set that is entirely true beats a comprehensive one people have learned to distrust. That is really the whole argument, and it is why the framing matters. Documentation has users, a quality bar, and a maintenance cost that never stops. Give it an owner, a review cadence, and one honest metric, and it stops being the thing everybody agrees to fix next quarter.