Why Documentation Projects Fail

Somebody nearly left, everybody got a fright, and a documentation project was announced. The pattern from there is consistent enough to predict.

Once the minimum record described in “Why Documentation Projects Fail” is defined, the practical challenge is keeping it current as work changes. A coordinator can use this implementation guide to plan review time, compare the effort attached to recurring processes and identify work that still depends on one person, without confusing activity visibility with proof that the underlying knowledge has actually been transferred.

For an independent benchmark, compare the local approach with Atlassian knowledge-sharing guidance; the useful test is whether ownership, access and recovery remain proportionate and explainable when the usual expert is absent.

The sequence

Enthusiasm for two weeks.

A template that turns out to be too detailed for anybody to complete.

Three people writing, one of them thoroughly and two barely.

Then a busy month, and it stops.

Eighteen months later somebody finds the folder and the contents are out of date enough to be misleading.

Why it stops

It is additional work with no immediate return. The person writing already knows the thing; the benefit accrues to somebody hypothetical.

The scope is undefined, so it never feels finished and therefore never feels urgent.

And the format is usually wrong: a template designed for completeness rather than for use.

The worse outcome

Documentation that exists and is wrong is more dangerous than none.

Somebody follows it, it is out of date, and the error is attributed to them rather than to the document.

After that people stop trusting the folder, which removes the benefit of the parts that are still correct.

What works instead

Write in response to a question. Somebody asks how something works; the answer gets written once, where it can be found, instead of explained again.

Write at the moment of the exception: when something unusual happens and somebody works out why, that is a note.

Write during handovers, when the knowledge is being transferred anyway and writing costs almost nothing extra.

And write short. Five lines that are read beat two pages that are not.

The trigger habit

The rule worth adopting: if you explain something twice, write it down the second time.

Not a project, not a template, not a deadline.

It costs three minutes at the moment when the explanation is already fresh, and over a year it produces documentation shaped by what people actually ask.

Where projects do make sense

A specific, bounded thing: one process, one client account, one system, with a date.

Before a known departure, where the scope is "what this person knows about these four things".

And where a client or regulator requires it, in which case the format is prescribed anyway.

Bounded works. Comprehensive does not.

The measure that matters

Not how much exists. Whether anybody has used it.

Ask: when did somebody last answer a question by looking something up rather than by asking a person?

If the answer is never, the documentation is not working regardless of its volume.

What to check

Has your organisation attempted a documentation project, and where did it stop?

Is anything in your folder out of date enough to mislead?

Do people look things up, or ask?

And does anything get written when a question is asked twice?

The point

Documentation that exists and is wrong is more dangerous than none, because somebody follows it and the error is attributed to them rather than to the document..

Underlying all of this

Everything in this collection reduces to four habits: know where the dependence sits, do the cheap fixes first, use the absences that already happen as rehearsals, and decide deliberately about what remains. None of it requires a framework, a tool or a consultant, and an organisation that does those four things consistently is substantially harder to damage than one with a succession document nobody has read.