Software Is Not Magic

We're just not explaining it well enough

When I was a fresh engineering manager, I kept going to my boss with the same complaint: I don’t understand my team’s domain. I don’t understand the services. I don’t understand the flows. I don’t understand the reasons behind half the decisions. And every time, he gave me the same line back:

“Software is not magic.”

It took me a while to hear what he was actually saying. He wasn’t telling me to try harder. He was telling me that if a system feels like magic, if it can only be operated by its author, if every question about it requires an oracle - that’s not a property of the software. That’s a communication failure. Somebody built it, somebody made every single decision inside it, and every one of those decisions has a why that can be said out loud in simple words.

Six months later I had moved the wrong engineers off the team, and the domain became clear almost overnight. Not because the systems got simpler - they didn’t, not at first. Because the new hires could finally explain them. Everything I “couldn’t understand” for months turned out to be perfectly understandable. The communication turned out to be the missing piece.

The Thread

Here’s what this looks like in practice, lightly disguised.

An engineer on my team ships a large PR introducing a brand new subsystem. Two services, infrastructure scripts, a forked open-source library. The PR description is a bullet list of file changes. I ask the most basic question a reviewer can ask: can you quickly summarize what’s in here?

What follows is a Slack thread with over a two hundred messages.

Every answer opens a new door I didn’t know existed. The library we forked? The upstream is dead - “it doesn’t update,” delivered as reassurance. One of the services pushes code directly onto the machines it manages, because that was “a solution to have a single versioned deploy.” There’s a cron job running every five minutes - why five? “Just copied it from another system, no particular reason.” The whole thing runs on its own VM outside our standard platform, and after twenty minutes of drilling, the honest answer surfaces: the standard platform’s dev experience is painful, so it was avoided. And the worst part was that this “plan” was never written down, it just happened.

None of these decisions were hidden on purpose. Every time I asked, I got an honest answer. But I had to ask. Every. Single. Time.

Ninety minutes in, I gave up extracting and wrote the summary myself:

So let me rephrase this entire thread such that I understand it correctly. We took a library, changed a lot of it to fit our needs. Our version is responsible for X on each machine. We put a second service on top that manages the machines. Yes / no / almost there?

The answer: “Yeah, that’s the gist.”

The gist was three bullets. Three bullets that existed in the engineer’s head the entire time, that could have been the first message in the thread, the first paragraph of the PR description. Instead, I had to spent two hours of archaeology to dig them out.

And here’s the part that makes this story interesting rather than just annoying: the design was mostly fine. When we finally got to the bottom of each choice, most of them held up. The engineer wasn’t defensive, wasn’t hiding anything, had reasons for nearly everything. Sometimes the software is genuinely good - it’s only the explanation that’s missing. That’s exactly the point. Nothing in that PR was magic. It just cost two hours of my time to prove it, and that bill gets paid again by every future engineer who touches that system.

The Darker Version

That thread is the recoverable version of the problem. There’s a worse one.

Earlier in my career as an EM, I inherited an engineer with a glowing reputation. Multiple great people, independently, told me he was the most brilliant engineer on the team - one said “much better than me,” which set the bar high. I had genuinely high hopes.

What I actually experienced: systems shipped to production that nobody else could explain or safely touch. Features that were “done” but that the rest of the team quietly cleaned up after. And in every conversation where I tried to understand his work, the same fog - not because he was hiding anything, but because translating his own decisions into words other humans could use was a skill he didn’t have and didn’t think he needed.

Managing him consumed more of my energy than the rest of the team combined (and multiplied). I tried coaching. I tried daily check-ins, written updates, feedback delivered every way I knew how. And eventually I had to be honest with myself: super smart, poor communication skills, and I could not coach him out of it. We parted ways.

The team’s domain didn’t get easier after he left. The explanations got better. That’s when my boss’s line stopped being a slogan and became an operating principle.

The Take for Leaders

When you don’t understand your team’s domain, your first hypothesis should not be “I’m not technical enough” or “this domain is just hard.” Your first hypothesis should be: someone on this team is failing to explain. Run the cheap test - ask for the three-bullet gist of any system. An engineer who understands their system can produce it in minutes. If a hundred-reply thread comes back instead, you’ve found your problem, and it isn’t the software.

Then comes the decision everyone frames wrong. The standard advice is that firing is the expensive option and coaching is the cheap one. After years of managing engineers, I believe it’s the other way around. Coaching a senior engineer to communicate is the expensive option:

To be clear: coaching is a genuine service to that engineer. If it works, they walk into the rest of their career with a skill that will out-value most technical skills they have. If you can afford it - the time, the team’s patience, the odds - it’s the more ethical choice, and I respect leaders who make it (and I aspire to be one myself whenever applicable).

But notice what else you could buy with that time. Every hour you spend coaching a genius to communicate is an hour you could spend understanding the systems yourself. Your team is better off with a more knowledgeable leader than with a slightly-better-communicating genius. When I finally moved the wrong engineers off my team, it forced me to drill into the tech debt personally - and that helped team a lot overall.

So the honest version of the take: coach if you can afford it. If you can’t, exit and move on (even though admitting this bit sucks for me now to be frank).

The Take for Engineers

If you’re the engineer in these stories, the fix is not a personality transplant, it takes deliberate practice to get better at communication. Maybe I will write a blog post about it one day.

The engineers I now hire and keep are not the ones who build the most impressive systems. They’re the ones who can make any system - including the messy, inherited, genuinely complicated ones - feel obvious after ten minutes of conversation. That skill is rarer than raw technical brilliance, and in a product team setting it’s worth more.

An Honest Caveat

Is there a carve-out for genuinely hard domains - distributed systems, parallelism, machine learning, the deep internals where maybe things really are irreducibly complex and there is no other way around it? Probably, somewhere. My years in this industry, both as IC and as an EM, and every single time something felt like magic, the problem was in the communication and not in the inherent complexity.

So that’s my prior until reality corrects me. When software feels like magic, don’t be impressed. Ask for a tldr :)

Software is not magic. We’re just not explaining it well enough.