The Day the Engineer Left, We Realized: No One Actually Understood That System

The message that day was short. Just two lines: "Can we talk? I might be leaving next month."

Then a long, very polite paragraph about "wanting a change."

The moment we read it, the first reaction wasn't sadness — it was a brief wave of dizziness. What flashed through our heads wasn't "where is he going," it was —

"Who's going to take care of that system?"

One person's head, holding up the entire operation

Almost every small company that makes it to year three has someone like this.

Maybe it's the engineer friend who helped build the website early on. Maybe it's the first technical hire who came in later. Maybe it's the founder themselves. They're not necessarily the most skilled person on the team, but they're the only one who knows why that one section was written the way it was.

Why does a particular piece of logic look the way it does? Because a long-time customer's order got stuck three years ago and it was bolted on to fix it. Why are there two membership-tier fields in the back office? Because a data merge didn't line up and a backup field got left behind. Why does a checkout button quietly hide itself every Tuesday? Because a promotion never got properly taken down and no one bothered to fix it.

None of this is written down anywhere. It lives in that one person's head.

We thought we owned a system. What we actually own is years of operating history running on memory.

A two-week handoff can't replace three years of memory

The two weeks after that resignation message were the most anxious two weeks.

We started asking him to record videos, write documentation, schedule meetings — all at once. Every day, a new set of Markdown files would appear, titled "Payment Logic Explained," "Membership Data Structure," "Product Listing Workflow."

In that moment, it felt like everything would be fine in time.

But once he actually left, the new person took over, and something unexpected happened in the first month, we realized:

Those documents explained how the system currently works. They never explained why it was designed that way in the first place.

And it's never the former that actually trips you up. It's always the latter.

Documentation isn't written for engineers — it's written for our future selves

A lot of people assume "writing documentation" is an engineer's job, some kind of technical fastidiousness.

But what will actually make you thank your past self three years from now is a set of decision records nobody ever reads while things are calm — why this payment provider, why we decided not to support LINE Pay, why membership tiers went from three levels down to two.

These things look trivial. But they're exactly what makes a system possible for someone else to take over.

And they're the last line of defense that keeps you from having to tear everything down and rebuild from scratch on the afternoon an engineer walks out the door.

(Reaching this point is completely normal — most small companies survive first and only get around to this once they have the slack to. Not having documentation doesn't mean you did something wrong. It just means life hasn't forced the issue yet.)

In the AI era, documentation matters more, not less

These days everyone talks about how much code AI tools can write for engineers, how many bugs they can help squash.

But we've slowly realized something: AI can only actually help once it can understand our system.

When documentation is thorough, AI can quickly read the code, suggest changes, even help with day-to-day maintenance. When documentation is a blank page, AI ends up just as lost as we are — staring at uncommented code, equally confused.

In other words, documentation used to be written for the next engineer. Now it's written for the next engineer plus an AI assistant that's on call twenty-four hours a day.

We don't need to turn every line of code into an essay. We just need to leave a sentence or two of "why" behind every meaningful decision, so the next person — or the next AI — has a real chance of picking the system up.

What actually survives isn't the code. It's the context

Engineers leave. There's nothing strange about that.

People move on, companies change phases — that's healthy.

What's not healthy is the whole team staring blankly at a screen on the day it happens, not even knowing where to start looking.

So instead of asking "when will we find the next engineer," the more useful question might be:

"If he walked out today, how much of this could we actually hold on to?"

What you get to keep was never the code. It's the context.

(For what it's worth, this article is itself a piece of documentation — written for a future version of us who might forget, three years from now, why any of this felt so urgent today.)