Software Documentation: When Code Outlives the People Who Wrote It

Software tends to outlive the plans made for it. A system built with a five-year lifespan in mind can end up running for a decade or more, accumulating decisions and workarounds that nobody thought to document it along the way. That knowledge doesn't leave only when the people who built it do — sometimes it goes quietly out of date while they're still on the team. Here's what I observed happened when a company found out how expensive that gap can get.

A hardware company had built an impressive chip tester, the kind of machine used to test computer chips before they ship. It was expensive and powerful, built to push hard against the limits of what its own hardware could do. The hardware team kept pushing it forward, cycle after cycle, adding new capability with every release.

Eventually, the software couldn't keep up. 

It became the bottleneck, holding back everything the hardware could otherwise do. So the company did what sounds reasonable on paper. It intended to scrap the old software and to rewrite it from scratch.

They spent millions on the rewrite. And they failed.

Not because the new team couldn't write code. They failed because they'd badly underestimated how much knowledge was buried inside the old software. Years of accumulated details and hard-won experience had gone into that codebase, one decision at a time, and none of it had ever been documented outside of the code. 

Without that record, the new team couldn't tell how much work it would take to match what the old version already did.
In the end, the company was back to maintaining the software they'd tried to replace, millions of dollars poorer for the attempt.

This isn't a rare story, either.

It's probably a common failure that plays out across the industry, wherever software has been running long enough to build up more knowledge than anyone bothered to write down.

Software Lives Longer Than People Plan for

Most teams build with a short horizon in mind, whether it's a prototype, a product cycle, or a system that will "probably get replaced" in a few years. Then it doesn't get replaced.

We consistently underestimate how long software will stick around.

A system built with a five-year lifespan in mind often ends up running for a decade or more beyond that, the software equivalent of a construction trailer still parked on site, still in daily use, twenty years after the building it was meant for got finished.

Some industries, on the other hand, plan for the long haul from day one.

Systems in the defense industry, for example, can stay in service for around fifty years. By that point, the software isn't the only problem. The physical hardware underneath it, the motherboards and other components, often simply stops being manufactured, leaving teams to maintain software for machines nobody makes parts for anymore.

Compare that mindset to how a fast-growing young company thinks about "long-term."

For a fast-growing startup, "long-term" could mean five years. For an aviation company, it could mean fifty. Both build software. They just don't build it for anything close to the same length of time.

The gap matters because documentation decisions get made based on how long a system feels like it's going to last right now, not how long it ends up lasting.

If a team believes a system is short-lived, skipping the documentation feels like a reasonable trade. Nobody sets out to leave a decades-long system undocumented. They just don't realize, early on, how long it's going to be around.

Writing Code Always Wins Over Documenting it

Ask a developer, when time is short, whether to write the next feature or document the last one, and the feature wins almost every time. It's rarely laziness. It usually comes down to timing.

Writing code pays off immediately. Documentation works more like insurance, paid up front and rarely thought about until the one day it's needed. By the time that day arrives, often much later, the person who wrote the code has usually forgotten why they made the choices they did.

Most people forget a lot of their own code within half an hour of writing it. Come back to it six months later, and it can feel like reading someone else's work entirely.

That delay is why code usually wins the trade-off. Nobody has reliably measured how often teams think that far ahead instead of just reacting to whatever's urgent.

When the Person who Wrote it Doesn't Know

It's tempting to think this risk is only about people leaving. Someone quits, their knowledge walks out the door with them, and the team scrambles to fill the gap.

But there's a sharper version of this problem, and it doesn't require anyone to quit at all.

As part of my research I ran a telling experiment on myself. I had personally written a large share of a codebase and reviewed most of the changes made to it. I, naturally, considered myself about as close to an expert on that system as anyone could be.

I made one of my students challenge me and he asked: How long would it take to pull one piece of the system out and turn it into something reusable elsewhere?

I gave an estimate based on what I believed I knew about how the system was built.

Then we ran a formal check of how the system's pieces connected to each other, and the real picture looked nothing like what I'd pictured in my head. My original estimate turned out to be off by a wide margin, and I had to rework it completely.

The person best positioned to know that codebase - me - had a mental picture of it that didn't match reality, and not because he'd been careless.

That's what happens to knowledge that only ever lives in one person's memory of decisions made over years, the way a mental map of your own neighborhood goes stale when the streets quietly change and nobody tells you.

It can already be wrong while that person is still sitting at their desk, long before anyone leaves.

What's Worth Writing Down

None of this is an argument for documenting everything. Code that needs a comment explaining what it does, line by line, is usually a sign the code itself needs to be clearer.

Good documentation skips the play-by-play of what the code does. It records why instead, including the assumptions behind a decision, the constraints that ruled out simpler options, and the reasoning that would let someone rebuild the thinking behind it without reverse-engineering it from scratch.

That's exactly the kind of detail that fades from memory first, and that a new hire has no way to guess just by reading the code, no matter how carefully they look.

The same logic applies to system architecture.

Teams often keep a separate document describing how a system is structured, and that document tends to drift out of sync with the code almost immediately because nothing forces the two to stay aligned.

A developer building against the documented design runs into a case the design didn't anticipate, deviates from it to ship on time, and moves on without ever updating the description.

From that point forward, the architecture diagram is just decoration, a framed blueprint on the wall of a house that's had two additions and a knocked-down wall since anyone last looked at it.

The only accurate account of how the system works lives in the code itself, and it's often unreadable at a glance to anyone who wasn't there when the deviation happened.

The Fix Needs Automation, not Just Discipline

Forget manually keeping two documents in sync.

What works instead is automated checks that keep comparing the actual code against the intended architecture, the same way automated tests keep checking that the software behaves the way it's supposed to. Drift gets caught the day it happens instead of the day someone needs the diagram to be true.

There's also a cultural piece to this.

Mistakes are inevitable in something as complicated as software, and the teams that handle this well still make plenty of them.

The habit of asking why a mistake happened, past the obvious, immediate cause, and sharing that answer with the rest of the team instead of letting it stay one person's private lesson is what builds continuity.

It keeps hard-won knowledge from getting stuck in a single person's head in the first place, which is the same kind of gap that left the chip tester's new team without what they needed.

When you Have Only one Choice

If you had to throw away either a piece of running software or its documentation, keep the documentation.

Good documentation lets you rebuild the software from scratch if you have to, the way a recipe lets you cook the same meal again once the plate's been cleared.

Software with no documentation gives you no real understanding of it. You can't safely change what you don't understand, and that makes it effectively useless. It hits a dead end the moment it needs to change hands, and eventually, all software does.

There's a newer version of this argument going around: that documentation and code readability barely matter anymore, because an AI can simply rewrite the software from scratch if it ever needs to change hands.

That's wrong.

It only works if the documentation exists. As the chip tester story shows, software is the accumulation of design decisions made one at a time over years, not just the code that resulted from them. If those decisions were never written down, they can't be part of the prompt. An AI has no more access to them than the new team did when they tried to rebuild the chip tester's software from scratch.