Translating Developer-Speak for Your Friends and Family

The Thanksgiving Turing Test

We have all been there. It is the fourth Thursday in November. You are cornered in the kitchen by an aunt holding a glass of Chardonnay that is slightly too warm. She looks at you with the aggressive curiosity of a colonial explorer and asks the question you fear most.

"So, what is it you actually do?"

You freeze. You consider telling the truth. You consider explaining that you spend your days wrestling with race conditions in a distributed system that was designed by people who hated each other. You consider describing the spiritual ecstasy of deleting three hundred lines of legacy code.

But you don't. You look at her, and you look at the cheese plate, and you say, "I work with computers."

You have failed. You have retreated. You are a spy who panic-bought a cover story at the dollar store.

The problem is not that your job is too hard to explain. The problem is that you know too much. Economists call this the "curse of knowledge," a cognitive bias where experts lose the ability to imagine what it is like to be ignorant. You cannot unsee the matrix. You cannot remember a time when "the cloud" sounded like weather. To you, an API is not an abstract concept; it is a waiter bringing you a plate of JSON. To your aunt, it is alphabet soup.

The unexpected utility of the metaphor

The only way out of this trap is to lie. Or, if you prefer, to speak in parables. You have to stop explaining the mechanics and start explaining the relationships. You have to build a bridge out of things your audience already understands.

You tell them that an API is just a waiter at a restaurant. You are the customer; the database is the kitchen. You do not need to know how the stove works. You just need someone to take your order and bring you the steak.

You tell them the cloud is a self-storage unit. It is just a big, secure building where you rent space to keep your digital junk so you don't have to stack it in your own garage.

You tell them a database is a library where the librarian is obsessively organized and possibly on amphetamines. You don't wander the stacks; you hand the librarian a slip of paper that says "find me every book with a blue cover published in 1994," and they bring you the stack in three milliseconds.

These are lies, of course. They are gross oversimplifications. But they are the only way to get to the truth.

The cost of speaking Elvish

The real danger here is not a boring Thanksgiving dinner. The danger is that this failure of translation follows you to work.

There is a version of the Thanksgiving conversation that happens every day in boardrooms and Zoom calls. Marketing asks for a feature. Engineering says "it's complicated." Management hears "we don't want to do it." Engineering hears "we want you to build a spaceship by Tuesday."

When we cannot explain the why behind the how, trust evaporates. The business side starts to view engineering as a black box that consumes money and emits excuses. Engineering views the business side as a chaos engine that generates impossible requirements.

This is where we usually say that engineers just need to get better at "soft skills." We tell them to be more empathetic. We tell them to take a communications workshop.

But maybe that is the wrong approach. Discipline is a finite resource, and I would rather my engineers spend it on writing tests than on figuring out the perfect metaphor for a load balancer.

The translator we hired

If we admit that translation is hard, and that experts are bad at it, then perhaps we should stop asking them to do it alone.

We built Doc Holiday to handle the grunt work of documentation, but its real value is translation. It is an automated anthropologist. It looks at the raw, messy reality of your codebase—the commits, the PRs, the technical debt—and it translates it into something a human being can actually read.

It is the universal translator for your engineering team. It takes the "what" (we updated the API schema) and helps you find the "so what" (this will break the mobile app if we don't update the client). It doesn't replace the engineer; it just handles the first draft of the explanation.

It allows you to be the genius who understands the system, without forcing you to be the poet who explains it. You can stay in the matrix. We will handle the aunt with the Chardonnay.