Why documentation projects stall, and what to do instead
The big documentation push is a recognisable pattern: three enthusiastic weeks, then nothing, then an apologetic restart a year later.
Almost every distributed team has attempted a documentation drive. Someone notices the gaps, a project is announced, a structure is designed, and for a fortnight a great deal gets written. For broader context on maintaining shared technical documentation, GitHub Docs is a useful reference.
Then the urgent work returns, the effort stops, and what remains is a half-populated structure that is worse than the ad-hoc state it replaced, because it now looks like it should be authoritative.
Why the big push fails
- It is a project with no end condition. Documentation is never finished, so there is no point at which anyone can declare success and stop.
- It is separated from the work, so it competes with delivery and loses every time.
- It produces material nobody asked for, written by whoever had capacity rather than by whoever knew.
- Nobody owns the result, so it decays from the week it is completed.
Anything that requires a dedicated push to produce will require a dedicated push to maintain, and the second push never happens.
Attach writing to things that already occur
The versions that survive are the ones bolted onto existing events, where the writing is a step in something that was happening anyway. For a practical software-side reference on time management and maintenance habits, this reading list adds useful detail.
A decision is not made until it is written. An incident is not closed until the runbook is updated. Onboarding includes fixing whatever the new person found wrong. A question asked twice becomes a page. None of these is a project, and together they produce more durable documentation than any drive.
Write in response to demand
Speculative documentation — writing what someone might need — has a poor hit rate and a high maintenance cost. Demand-driven documentation has neither.
The signal is free and continuous: the questions people actually ask. Keeping a rough tally of repeated questions produces a prioritised list far better than any audit of what is missing.
Budget the time honestly
Teams that value documentation and allocate no time for it are teams that do not value documentation. The work is real and it competes with delivery.
A modest standing allocation — a few hours a week, owned by a named person on a rotation — outperforms an occasional large effort, and it survives busy periods because it is small enough to be preserved.
Accept partial coverage
The goal is not completeness. A team where the ten most consequential things are documented, current and trusted is in far better shape than one with two hundred pages of uncertain accuracy.
Deciding explicitly what will not be documented is part of the discipline, and it is what makes the remainder credible.