Why documents drift
Documents rarely go wrong through a single mistake. They drift. A system changes a little at a time, each change is small, and updating the document is always the task that can wait until tomorrow. After enough tomorrows, the document describes a system that no longer exists.
Understanding the causes helps in choosing remedies. Common ones include:
- nobody is clearly responsible for the document;
- updating it is separate from, and later than, the work that changed things;
- the document repeats details that live elsewhere, so every change needs two edits;
- readers who spot errors have no easy way to report or fix them;
- there is no signal of how old a page is, so wrong pages look as trustworthy as right ones.
Each cause has a practical counter-measure. None needs heavy process.
Make ownership explicit
A document with no owner is usually a document with no future. Name an owner for each important page, preferably a role or small group rather than one individual who may move on. The owner is not obliged to write everything; they are the person who makes sure it gets looked at. When people change roles, handing over documents should be part of the handover, along with the work itself.
Record the owner and a last-reviewed date on the page. This gives readers a quick way to judge reliability, and gives the owner a reminder of what needs a look.
Update documents as part of the change
The most effective habit is to treat a document change as part of the work that makes it necessary. Pull requests that alter behaviour should also alter any document, comment or diagram that describes that behaviour. Many teams add a line to their review checklist: “Have the related documents been updated?” It costs seconds and catches a surprising amount of drift. It is much easier to make the edit while the details are fresh than to reconstruct them later.
For changes that are not tracked in code, such as altering a process or replacing a piece of equipment, the equivalent is to include a documentation step in the plan for the change. A change is not finished until the people who rely on the documents can find out about it.
Keep documents close to what they describe
Documents that sit next to the thing they describe are noticed more often. Material about code can live in the repository, so that a person editing a file sees the related notes. Explanations of a procedure can sit with the equipment or the tool where it is used. Version history helps here too: a document under version control shows when and why it changed, and allows an old version to be recovered if needed.
Distance is a real cause of staleness. A page in a rarely visited corner of a wiki can lose touch with reality for years.
Say each thing once
Every fact repeated in several places is a fact that must be updated in several places. Where possible, keep one authoritative source and have other documents refer to it. A table of settings, a list of contacts or an interface definition should live in one place only. Writing “see the interface description for current values” may be less convenient for the reader than copying the values, but it can be much safer.
Generated documentation is a related option. If a reference can be produced from the code or configuration itself, it follows changes automatically. This works best for factual reference material. Explanations of intent and context still need a human to write and to review. Similarly, tests that capture expected behaviour, including unit tests, serve as documentation that fails loudly when it becomes wrong.
Add review triggers and a light routine
Some documents should be reviewed at fixed moments rather than left to chance. Useful triggers include:
- a release, a milestone or the end of a project phase;
- a change of equipment, tools or suppliers;
- an incident or a near miss, when the response revealed that a procedure was unclear or wrong, which blameless reviews are well placed to uncover;
- a new person joining, whose first attempt to follow the documents is a free test.
That last trigger deserves attention. A new colleague who follows the instructions is the best detector of drift, and engineer onboarding often brings stale material to light within days. Ask newcomers to note anything that did not match reality, and make fixing it part of their first weeks.
In addition, a light routine helps. A short periodic review of the most heavily used documents, perhaps every few months, is more realistic than a large, rare audit. The review can be quick: is this still true, is it still needed, and who owns it?
Make fixing easy
If the process for correcting a document is awkward, errors will linger. Allow readers to edit pages directly, or to leave a comment or open an issue with one click. Respond quickly and thank people who report problems. Nothing discourages feedback like a report that disappears.
Where documents are controlled for regulatory or quality reasons, direct editing may be inappropriate, and formal change processes apply. In those cases, make the route to propose a change as simple as the rules allow, and follow the standards that apply to your industry and country.
Retire what is no longer useful
Not every document should be kept alive. Pages that describe retired systems, abandoned plans or superseded procedures mislead readers and dilute the good material. Archive or delete them, or mark them clearly at the top as obsolete, with a pointer to what replaced them. Fewer, better-maintained documents are normally more useful than many neglected ones.
Accept some imperfection
No team keeps every document perfectly current. The aim is not perfection but trust: readers should be able to rely on the important documents, and see at a glance which ones are uncertain. A visible date, an owner and a candid note such as “this section has not been checked since the last redesign” help readers calibrate. Prioritise the documents that people depend on in risky or time-pressured situations, such as procedures for fault recovery, since errors there cost the most.