Why internal docs go unread
The usual explanation is that people are lazy or that the writing is bad. Neither is generally true. The real reason is that reading a document is a gamble and asking a colleague is not.
When someone opens an internal doc, they are asking two questions in the first few seconds: is this current, and does it answer my question? If either answer is unclear, asking someone in chat is faster and carries no risk of acting on stale information. That is a rational choice, and no amount of encouraging people to "check the docs first" will beat it.
The reason most docs fail
It is not length and it is not writing quality. It is that the reader cannot tell whether the document is still true. Everything else in this article is downstream of that.
The structure that gets read
Owner and last reviewed date, at the very top
A named person and a date, above the content. Not in a footer, not in page metadata that nobody looks at.
This single element does more than everything else combined. A reader who can see a document was reviewed last month will trust it. One who cannot tell will go and ask someone.
Above the contentThe answer in the first two lines
State the conclusion before the context. "Expenses over 200 need approval from a manager before purchase, through the form linked below."
Most internal docs open with background. The reader wanted one fact and has to read four paragraphs to find out whether it is even here.
Conclusion firstOne document per question
If a document answers six questions, it will be found by people looking for one of them and skimmed badly by all six.
Splitting is nearly always right. Small linked documents beat one comprehensive page, which is usually a sign that nobody wanted to decide what belonged where.
Split, do not consolidateDecisions and exceptions, not just steps
The steps are the easy part. The value is in what to do when the situation does not match: the exceptions, the edge cases, the judgement calls.
This is also the knowledge that exists only in one person's head, which makes it the most expensive thing to lose.
Exceptions are the valueSay what happens when it goes wrong
The two or three common failures, what to do about each, and who to ask for anything else. Name a person.
A document with no escape hatch gets abandoned the first time reality diverges from it, and the reader concludes the docs are unreliable rather than incomplete.
Name a humanLink out rather than repeating
Never copy content from another document. Link to it.
Duplicated content is guaranteed to fall out of sync, and then you have two documents disagreeing, which is worse than having none.
One source per fact
What is worth documenting
Not everything. The instinct to document comprehensively is how knowledge bases become graveyards.
| Worth writing | Skip |
|---|---|
| Things only one person knows how to do | Anything obvious from the interface |
| Decisions and why they were made | Meeting notes as reference material |
| Exceptions and edge cases | Step-by-step click paths that change monthly |
| Anything done rarely enough to be forgotten | Processes about to change |
| Onboarding context for a new person | Aspirational process nobody follows |
The last one deserves emphasis. Documenting the process you wish you had rather than the one you actually run produces a document that everyone quietly ignores, which then teaches people that all the documents are aspirational.
Our guide to documenting a process covers the step-by-step type specifically, including the test of handing it to someone who has never done the task.
Making it findable
One home, no exceptions. Whichever tool you use, everything goes there. The moment there is a second location, nobody knows which is authoritative and both decay.
Title it as the question. "How do I get an expense approved?" gets found. "Expenses Policy v2" does not, because nobody searches for the words in it.
Keep an index page. Twenty documents grouped by area, maintained by a person. Search alone is not enough, because people cannot search for something they do not know exists.
Link from where the question arises. The best-read documentation is linked from the tool or the moment where someone hits the problem, not filed in a wiki they have to remember.
Keeping it out of the graveyard
Three habits, all cheap, that prevent the slow death:
Updating the doc is part of changing the process. Not a follow-up task. If someone changes how invoices go out, the change is not finished until the document reflects it. This is the only rule that genuinely prevents rot, because every other approach relies on remembering later.
A six-month review, honoured. Long intervals that actually happen beat quarterly reviews that get skipped. The owner re-reads, updates the date, or marks the document obsolete.
Delete aggressively. An out-of-date document is worse than a missing one, because someone will act on it. Archiving something nobody has opened in a year costs nothing and makes everything around it more trustworthy.
One honest caveat about writing style: most internal documentation is over-formalised. People write internal docs as though they were legal documents, which makes them slower to write, duller to read, and harder to update. Write them the way you would explain it to a new joiner sitting next to you. That version is more accurate, because you would never say something vague out loud to someone who was about to go and do it.
Where this matters most is onboarding. A new person in their first week is the only person who can see exactly where your documentation is thin, and only for about three weeks before they normalise. Our guide to onboarding a new hire in their first five days covers how to capture what they tell you while the gaps are still visible to them.
Frequently asked questions
- Why does nobody read our internal documentation?
- Usually because readers cannot tell whether a document is current, and being wrong is worse than asking a colleague. An owner and a review date at the top fixes more of this than any amount of rewriting.
- How long should an internal document be?
- As long as the question needs, with the answer in the first two lines. Length is rarely the reason something goes unread. Burying the answer under context is, because the reader cannot tell in five seconds whether they are in the right place.
- Where should internal docs live?
- In one place, whichever it is. Two locations mean nobody knows which is authoritative, and the fastest way to kill a knowledge base is to start a second one somewhere else.
- Who should own internal documentation?
- A named person per document, not a team. Shared ownership means nobody notices when it goes stale. The owner is not necessarily the author, but they are the person who is asked when it turns out to be wrong.
- Should documentation be written by the person who does the work?
- Yes, with a second person asking questions while they write. Written alone, people skip the steps that have become automatic, and those are exactly the steps a newcomer gets stuck on.