I run product and design, so I spend most of my day thinking about why people use a thing or ignore it. When I started applying that same lens to our internal documentation, the picture got uncomfortable fast. We had hundreds of docs. People read almost none of them. The same questions got asked in chat every week, the same context got re-explained on every onboarding call, and the wiki sat there like a museum of good intentions. The docs were not failing because the writing was bad. They were failing because nobody had ever treated documentation as a product with real users and a real job to do.
That reframe is the whole argument. A product has users you can name, a purpose you can state, and a maintenance plan that keeps it from rotting. Most internal documentation has none of those. It is written once, by whoever happened to know the thing, in a hurry, for an imagined reader who does not exist, and then abandoned. Knowledge management is not a writing exercise. It is a product problem, and it responds to product thinking.
Most docs fail because they have no user
Ask someone who they wrote a doc for and you usually get a blank look. They wrote it because they were told to, or because they wanted the knowledge out of their head, or because a process required an artifact. None of those are users. They are reasons to produce a thing, not reasons for anyone to read it.
When you do not know the user, you write for everyone, which means you write for no one. The doc tries to cover everything, so it is long. It tries to be precise, so it is dense. It assumes either too much context or too little, because it never decided who is reading. The result is technically accurate and practically useless, the documentation equivalent of a feature nobody asked for. Good docs, like good products, start by being ruthless about who they serve. A runbook for an on-call engineer at 2am is a completely different artifact from an overview for a new hire in week one, and trying to make one document do both jobs guarantees it does neither.
Onboarding speed is the metric that tells the truth
If you want to know whether your documentation actually works, do not count pages or measure coverage. Watch a new person try to become productive. Onboarding is the honest stress test, because a new hire has no tribal knowledge to fall back on. They cannot tap the person next to them, they do not know which doc is current and which is a ghost, and every gap in your documentation becomes a question they have to interrupt someone to ask.
We started timing it. How many days until a new engineer ships something real. How many times in their first two weeks they had to ask a question that a doc should have answered. Those numbers are diagnostic in a way that nothing self-reported is. When onboarding is slow and interrupt-heavy, your documentation is broken regardless of how complete it looks, because completeness is not the goal. Being findable, current, and trusted at the moment of need is the goal.
Example: We watched a new hire spend most of her first day hunting for how to set up a local environment. The instructions existed. They were spread across three documents, one of which was a year out of date and contradicted the other two, and she had no way to tell which was right. The fix was not more documentation. It was one canonical, dated, owned doc and the deletion of the other two. Her replacement two months later was productive by lunch.
Treat docs like features: own them, version them, retire them
Here is what changes when you genuinely treat documentation as a product. Every important doc gets an owner, a single name accountable for whether it is true, the same way a feature has an owner accountable for whether it works. Ownerless docs are how you end up with a wiki full of confident, wrong information that nobody is responsible for and therefore nobody fixes.
Every doc gets a visible last-reviewed date, because trust is the entire currency of documentation. A reader who has been burned once by a stale doc will stop trusting all of them and go back to asking in chat, which is the failure mode you were trying to escape. A date does not guarantee accuracy, but it lets a reader make an informed bet, and that is most of what trust is.
And, the part teams resist most, you delete aggressively. A smaller set of documents you can trust beats a vast archive you cannot. Out-of-date documentation is worse than no documentation, because no documentation at least tells you to go ask, while wrong documentation confidently sends you in the wrong direction. We treat deletion as maintenance, not loss. Pruning the dead pages is what keeps the living ones credible.
There is a useful product instinct hiding in all of this, which is that you should write fewer docs, not more. Teams that treat documentation as a virtue tend to produce an endless sprawl of pages, each one written with the best intentions and none of them maintained, until the volume itself becomes the problem. A good product is defined as much by what it leaves out as what it includes, and the same is true here. Before we write a new doc we ask whether this is genuinely something people will need repeatedly, or whether it is a one-time answer that belongs in a thread. The goal is not coverage. It is a small, trustworthy set of documents that earn their keep, each one clearly the place to look for a specific thing, with nothing competing for that job.
Make documenting part of the work, not extra to it
The deeper reason docs rot is structural. In most companies, writing them is an afterthought that happens after the real work, when the energy is gone and the deadline has passed. So it does not happen, or it happens badly. The teams that get this right pull documentation into the workflow itself, so the doc is a byproduct of doing the thing rather than a separate chore bolted on afterward.
This is something we care about deeply in how we build Atlas, because async work lives or dies on whether the written record keeps up with reality. When the decision, the task, the project, and the document live in the same place, capturing knowledge stops being a context switch. The notes from a decision sit with the work that decision affects. The answer to a recurring question becomes a doc the next person finds instead of a message that scrolls away. Knowledge management works best when it is a side effect of working, not a second job.
None of this requires a heroic documentation initiative, and frankly those usually fail anyway. It requires a shift in posture. Stop asking how to get people to write more docs and start asking who each doc is for, whether it is current, and who is on the hook for it being true. Treat your documentation like a product, judge it by how fast people get productive, and the docs nobody reads quietly turn into the ones everyone relies on.