Member-only story
Editorials
The Engineer Who Left Took the Architecture with Them
Documentation isn’t the fix. It never was.
I was the single point of failure once. A messaging system I’d built mostly alone kept working after I moved on — for about four months. Then the team started making changes, and the failures followed patterns I would have recognized instantly. They didn’t lack talent. They lacked the why behind every decision I’d never written down.
In cultural anthropology, this is called the problem of oral tradition. When knowledge lives only in the minds of its holders, it survives exactly as long as those holders are present and willing to share. The Library of Alexandria wasn’t destroyed in a single fire — that’s a myth. It declined over centuries as the scholars left, one by one, taking their interpretations of the texts with them. The scrolls remained. The understanding didn’t.
Codebases decay the same way. The code stays. The reasoning behind the code leaves with the person who wrote it.
The most dangerous technical debt isn’t in your code. It’s in the gap between what your system does and what anyone currently on the team understands about why it does it.
I’ve seen three responses to this problem, and two of them don’t work.
