Documentation that is still true next year
Every team has documentation. The problem is that nobody trusts it, and untrusted documentation is worse than none.
The failure is not absence. Most teams have written a great deal. The failure is that some of it is out of date, nobody knows which parts, and so it is all treated as unreliable — at which point it stops being read and continues to be maintained. For broader context on maintaining shared technical documentation, GitHub Docs is a useful reference.
Fewer pages, owned
A large documentation set with no owners decays uniformly. A small one with a named owner per page stays alive.
Ownership has to be a person rather than a team, and it has to be visible on the page. 'Owned by engineering' is owned by nobody. A name and a date at the top of every page is the single highest-return convention in technical documentation. For a practical software-side reference on using written systems to reduce memory load, this resource adds useful detail.
Last reviewed, by whom. A reader can then judge for themselves whether to trust it, which is what makes the difference between documentation that is used and documentation that is merely present.
Write down what changes slowly
Effort should follow durability. Why the system is shaped this way, what the constraints are, what was tried before — these stay true for years and are the things nobody can reconstruct.
Exact click paths, screenshots of interfaces and version-specific instructions go stale in months and generate most of the maintenance burden. Where they are needed, isolate them so they can be replaced without touching the durable material.
Delete confidently
The instinct is to keep everything in case it is useful. The effect is that useful pages are buried among obsolete ones and search returns three contradictory answers.
Deleting is a service to readers. Where deletion feels risky, archive with a visible banner saying the page is no longer maintained — which is honest and lets someone judge it — rather than leaving it looking current.
Write it when you learn it
The best moment to document something is immediately after struggling with it, by the person who struggled. They know precisely what was not obvious, which the expert has forgotten.
This is why new joiners are the best documentation authors, and why 'write down what confused you' is a genuinely valuable first-week task rather than a make-work exercise.
Attach it to the work
Documentation kept in a separate system, disconnected from where work happens, is documentation that will not be found at the moment it is needed.
Link it from the ticket, the repository, the project. The test is whether someone arriving at a piece of work encounters its documentation without knowing to look for it.
Schedule the review, and keep it small
An annual review of everything is a project that will not happen. A rolling review — each owner checks their pages once a quarter, taking twenty minutes — does happen, because it is small enough to fit in a normal week.