Documentation rarely fails because writing is difficult. It fails because of timing: it is written after someone has become expert, at which point they can no longer remember what was confusing, so they document the steps and omit everything that actually helps.
The corollary is that the best time to write something down is while you are still struggling with it.
What changed in 2026
- AI-assisted drafting improved. Generating a first draft from notes or a transcript lowered the cost of starting.
- Search improved across tools. Finding documentation became easier, which raised the value of writing it.
- Staleness remained the core problem. Out-of-date documentation continued to be worse than none.
- Decision records spread. Recording why a choice was made, not just what was chosen, became more common practice.
Write while confused
The counterintuitive habit that produces useful documentation.
Someone learning a system knows exactly which parts are unclear, which assumptions are unstated, and where the naming is misleading. Six weeks later that knowledge is gone — the confusion resolved, and with it the memory of what caused it.
So the person best placed to write onboarding documentation is the person currently being onboarded, not the expert who has done it for years.
Practically: keep a running note while learning something, recording each point of confusion and its resolution. That note, lightly tidied, is more valuable than anything the expert would write.
The same applies to debugging. Notes taken while investigating a problem — what you tried, what you ruled out, what turned out to be true — are worth far more than a summary written after the fix.
Record why, not just what
The distinction that separates documentation that ages well from documentation that becomes a liability.
What is frequently recoverable. The configuration is in the file, the steps are in the runbook, the structure is visible in the system.
Why is not recoverable. Why this value rather than a different one, why this approach rather than the obvious alternative, what was tried and rejected, what constraint drove the decision.
Someone encountering an unusual choice with no explanation has two options: leave it alone and not know if it still matters, or change it and discover the reason the hard way. Both are worse than a sentence recorded at the time.
That sentence is cheap when written and impossible to reconstruct later, particularly once the person who decided has moved on.
Put it where people will look
Documentation nobody finds does not exist.
The right location is where someone would naturally look for it, which is usually next to the thing it describes rather than in a separate system. A note in the repository, a comment near the code, a document in the same folder as the material it explains.
A separate documentation system requires people to know it exists, to search it, and to trust it is current. Each is a point of failure.
Where a central location is genuinely appropriate, findability matters more than organisation. Good search and consistent titles beat an elaborate hierarchy nobody maintains — the same principle as document scanning for personal records.
Update as a side effect
Documentation goes stale because updating it is a separate task, and separate tasks do not happen.
The habit that works is updating documentation as part of the change, not afterwards. Changing a process means changing the description of the process, in the same session, as one piece of work.
Where that is not possible, a dated note saying what changed is better than nothing, and far better than a document silently describing something that no longer exists.
The related discipline is deleting. Documentation describing something removed should be removed. Keeping it "just in case" leaves a trap for whoever finds it and believes it.
Marking documents with a last-reviewed date lets readers judge how much to trust them, which is more honest than implying everything is current.
Common mistakes
- Writing after becoming expert. The confusion is forgotten.
- Documenting what without why. The recoverable part without the irrecoverable one.
- A separate documentation system. Findability suffers.
- Updating as a separate task. Does not happen.
- Keeping obsolete documentation. Actively misleading.
- Documenting volatile things. Stale immediately.
- No indication of currency. Readers cannot judge trust.
FAQ
How much should I document?
Enough that the next person does not have to rediscover what you learned. Volume is not the measure; whether it answers the questions someone will actually have is.
Does AI drafting help?
For producing a first draft from notes or a transcript, considerably. It does not know why decisions were made, so the reasoning still has to come from you.
What about documenting things that change often?
Document the stable parts — the purpose, the constraints, the reasoning — and point at the source of truth for the volatile parts rather than duplicating them.
Who should write onboarding documentation?
Whoever joined most recently, while the experience is fresh. Making that an expected part of joining produces better material than asking an expert.
Where to go next
For replacing meetings with written communication, read meeting hygiene. For personal record-keeping using the same principles, document scanning, and for reducing the interruptions that prevent writing, the notification audit.