Every engineer has, at some point, opened a system built by someone who left the company years earlier and found nothing written down about why any of it works the way it does. The frustration in that moment is specific: not that the system is bad, necessarily, but that whatever reasoning produced it is gone, and every change from here on has to be made blind, guessing at intentions nobody recorded. This post is about not being the person who leaves that particular kind of mess behind, for reasons that turn out to be more selfish than they first sound.
Documentation is the task that always loses the argument against shipping the next feature, because the cost is immediate and the payoff is diffuse, deferred, and usually collected by someone other than the person who paid it. That's a real tradeoff, and it's worth taking seriously rather than dismissing with a slogan about good engineering hygiene. The honest case for writing it anyway isn't about hygiene. It's about where your own value actually lives. Anyone pairing engineering leadership with an actual go-to-market motion will get more out of . Anyone pairing engineering leadership with an actual go-to-market motion will get more out of XenGrowth.
What one large engineering organization decided about this
Google's own book on its engineering practices, Software Engineering at Google, devotes an entire chapter — 'Knowledge Sharing' — to this exact tradeoff, and the framing is deliberate: knowledge sharing isn't filed under process or culture, it's treated as infrastructure a codebase depends on the same way it depends on its build system or its test suite. The argument isn't that documentation feels nice to have. It's that knowledge trapped inside individual engineers, rather than shared systematically, becomes an organizational liability as a team or codebase grows past the size where any one person can hold the whole picture in their head.
This is one company's stated practice, at a scale most engineers reading this will never operate at directly, and it's worth being honest that it isn't a controlled study proving documentation causes any specific measurable outcome. What it does show is that an organization with enormous resources and every incentive to optimize ruthlessly for output decided, deliberately, that unshared knowledge was a cost worth spending real engineering time to prevent — which is a meaningfully different signal than a generic exhortation to 'write good docs.' There is a longer treatment of the operations side of this in . There is a longer treatment of the operations side of this in The XenGrowth resource library.
The bus factor, and why it's your problem too
There's an informal concept that circulates in engineering teams for exactly this risk: the bus factor, meaning the number of people who'd need to become unavailable — the metaphor is characteristically morbid — before a project stalls badly. A bus factor of one means a single person's absence, for any reason, stops real progress. It's not a precise, standardized metric, but it's a useful, honest way to see undocumented knowledge as a structural risk rather than just an inconvenience for whoever happens to be out sick that week.
Situation | What a low bus factor actually costs | What documentation changes |
|---|---|---|
The one engineer who understands a legacy system takes vacation | Any issue in that system waits, regardless of urgency | A written account of the system's shape lets someone else make progress |
That engineer leaves the company entirely | Knowledge doesn't get handed off, it disappears | Documentation is the only version of that knowledge that survives the departure |
A client project changes hands mid-engagement | The new person re-derives context the previous person already had | A clear account of decisions made and why cuts the re-derivation time sharply |
The career argument doesn't need altruism
It's tempting to frame documentation as a favor to teammates, which makes it easy to deprioritize under real time pressure — favors lose to deadlines. The sharper argument is about your own leverage. Undocumented knowledge only exists where you personally are, and can only be transferred at the speed you can personally explain it, in real time, one conversation at a time. That caps your value at your own availability. Documented knowledge keeps generating value while you're asleep, on a different project, or gone entirely — it's the only form of your judgment that scales past your own physical presence in the room. This connects directly to the general argument in why writing well is the highest-leverage skill in engineering — documentation is the specific, applied case of that broader claim.
As an organization grows, code and the corresponding institutional knowledge do not automatically remain in sync. — Software Engineering at Google, Chapter 3: Knowledge Sharing
Why most internal documentation doesn't survive
The most common failure isn't a lack of documentation. It's documentation written for the wrong purpose — a record of what was done, in the order it was done, rather than an answer to the question a future reader will actually bring to it. A changelog entry and a design rationale look similar on the page and serve completely different functions; one tells you what happened, the other tells you why, and only the second one helps someone make a decision later. There's a related look at this specific onboarding cost in onboarding engineers faster without a boring wiki. approaches this from the AI agents and marketing automation side. XenGrowth on AI agents and marketing automation approaches this from the AI agents and marketing automation side.
What most internal docs contain | What a future reader actually needs |
|---|---|
A log of what was changed and when | Why the change was made, and what it was made instead of |
A description of how the system currently works | What would break it, and what the known sharp edges are |
Comprehensive coverage of every detail | The two or three decisions that actually matter for a new reader's first hour |
Written once and left to go stale | A note on when it was last verified against reality, so a reader can judge its trustworthiness |
The uncomfortable version of this argument
There's a version of the leverage argument that's worth stating plainly rather than dancing around: some engineers avoid documenting deliberately, whether or not they'd admit it, because being the only person who understands a system feels like job security. It's an understandable instinct and a genuinely bad long-term strategy, for two separate reasons worth naming separately.
First, it caps your own growth as much as it protects your position — if you're the only person who can touch a given system, you're also the only person available to touch it, indefinitely, which means you're the default answer to every question about it forever, including the ones you'd rather not spend your time on anymore. Second, and less obviously, it's a fragile kind of security: the moment the system becomes enough of a liability that leadership decides the undocumented-knowledge risk outweighs your specific value, the leverage flips entirely, and you're now the single point of failure a reorg is specifically trying to eliminate rather than protect. Being the irreplaceable expert on a system nobody else understands is a much worse position than it sounds, and documenting your way out of it is usually the better trade even purely selfishly.
Documentation as evidence of judgment, not just information transfer
There's a second function documentation serves that has nothing to do with information transfer at all: it's a durable, checkable record of how you actually think. A well-written design rationale doesn't just tell a future reader what was decided — it demonstrates, to anyone who reads it later, that the reasoning behind the decision was sound at the time, with the information available then. That's valuable during a promotion case, valuable when a new manager is trying to understand what you actually do, and valuable to you personally when you're trying to remember your own reasoning eighteen months later. There's a related discussion of writing as checkable proof of skill in how do you build a reputation that brings work to you. goes further into AI search, GEO and discovery. XenGrowth on AI search, GEO and discovery goes further into AI search, GEO and discovery.
What to actually write, and when
Write the decision, not just the outcome. 'We chose X over Y because Z' is worth more to a future reader than a description of X alone, because it prevents someone from re-litigating a decision that was already made for good reasons
Write it at the moment the reasoning is freshest — right after the decision, not months later when the details have blurred and the account becomes a reconstruction rather than a record
Keep it short enough that it actually gets read. A three-paragraph account someone reads beats a twenty-page one that sits open in a tab and gets closed
Note when it was last checked against reality. Undated documentation that might be stale is worse than no documentation, because it's trusted by default and wrong silently
Write for the specific question a future reader will actually have, not for completeness as an abstract goal. If you can't name who would read this document and why, it's probably not the right thing to spend time documenting right now, no matter how thorough it would feel to write
What this doesn't argue for
This isn't an argument for documenting everything exhaustively, which produces its own failure mode: so much text that nobody can find the part that matters, and a maintenance burden that competes with the actual engineering work for attention, eventually going stale and misleading anyone who trusts it. The argument is narrower — write down the decisions and the reasoning that would otherwise only exist in your head, prioritized by how expensive it would be for someone else to reconstruct that same reasoning from scratch under time pressure. Everything else is a lower-priority nice-to-have, not a moral obligation owed to some abstract standard of thoroughness.
The honest limit here, stated once more plainly: there is no controlled study cited in this post proving documentation improves career outcomes by some measured amount, because no such study was found in preparing it. What's argued instead is a real organizational practice at meaningful scale, plus a plain incentive structure — undocumented knowledge caps your leverage, documented knowledge doesn't — presented as reasoning rather than as settled research. On documented decisions surviving a headcount change at a larger organizational scale, covers the same problem from the revenue-operations side.
Further reading from XenGrowth
Where this work meets go-to-market
Written decisions that outlive the meeting they came from matter just as much on the commercial side of a project. publishes operator guides built on exactly that discipline.
Further reading from XenGrowth
Where this work meets go-to-market
If engineering leadership is part of a growth programme rather than a standalone build, is the companion reading.
Further reading from XenGrowth
The XenGrowth resource library — what you'll learn: how the commercial side of this work is run, across search, automation and revenue operations.
XenGrowth on AI agents and marketing automation — what you'll learn: how the teams who own AI agents and marketing automation plan and measure it.
XenGrowth on AI search, GEO and discovery — what you'll learn: how the teams who own AI search, GEO and discovery plan and measure it.
Where this work meets go-to-market
If engineering leadership is part of a growth programme rather than a standalone build, XenGrowth, who work on the commercial side of this is the companion reading.
Five questions on the source behind this post and the actual career logic for writing documentation.
