I Spent Three Hours Arguing With a Sommelier and Learned Something About APIs
A wine dinner in Richmond turned into the most clarifying conversation I've had about interface design in years. The sommelier didn't know what an API was. That's exactly why it worked.
How It Started
My wife dragged me to a wine pairing dinner at a place in Richmond that charged too much and dimmed the lights to the point where I couldn't read the menu. Fine. I was off the clock. I put my phone in my pocket and decided to be a person.
The sommelier came around — late thirties, French accent, spoke about wine the way engineers speak about systems they built and genuinely love. I made the mistake of asking a real question instead of nodding politely. Three hours later, we'd covered malolactic fermentation, Burgundy's appellation politics, and somehow, without either of us noticing the turn, exactly what's wrong with how I design software interfaces.
The Thing He Said About Burgundy
He was explaining why two bottles from vineyards separated by thirty meters could taste completely different and command wildly different prices. The soil, the drainage, the angle of the slope. I said something like, "So the same inputs produce radically different outputs based on invisible infrastructure." He looked at me the way people look at dogs that do something unexpected. "Yes," he said. "Exactly that."
Then he flipped it. He said the best producers don't try to explain all that to the person drinking. They just make the bottle legible at the moment of choice — the label, the vintage, the appellation, three data points — and they trust the drinker to engage as deeply as they want. The complexity is real. The interface hides none of it and surfaces only what you need right now.
"The complexity is real. The interface hides none of it and surfaces only what you need right now."
Why That Lit Something Up in My Brain
I have spent fifteen years watching engineers — myself included — treat API design as a documentation problem. We build something genuinely complex, then we write a spec that explains the complexity, and we call that good interface design. It isn't. It's a map of the inside of our heads. The sommelier's label isn't a technical manual. It's a decision surface.
The question isn't "how do I explain what this does." It's "what does the person standing here, right now, need to know to take the next step." Those are completely different problems. We almost never ask the second one.
The Argument Part
I pushed back. I said wine has the luxury of sensory feedback — you taste it, you know immediately if it worked. Software APIs don't have that. The feedback loop is longer. Integration takes weeks. By the time you know the interface was confusing, you've already written ten thousand lines against it.
He didn't concede the point, which I respected. He said that's not a difference in the problem, it's a difference in the stakes. Wine that doesn't communicate well at point of selection doesn't get opened. APIs that don't communicate well at point of integration don't get adopted, or they get adopted wrong and you spend the next two years fielding support tickets that are really just the ghost of a bad first impression.
He was right. I hate when that happens.
What I've Actually Changed
I came home and looked at three internal APIs my team owns. Asked a single question for each one: what is the minimum information a competent developer needs to make the first correct call. Not the full picture. Just the first correct call.
Two of the three APIs failed that question badly. The reference docs were thorough and the getting-started guides were disaster. The ratio was backwards. We'd optimized for completeness over legibility at the moment of entry. Classic error. Obvious in retrospect. Invisible until a French sommelier accidentally surfaced it over a glass of Gevrey-Chambertin.
The Part Where I Admit the Real Problem
We design for ourselves. Not maliciously — we just know the system so well that we've lost the memory of not knowing it. The sommelier knows every vineyard in Côte de Nuits. He didn't design the label for himself. He designed it for the version of himself from twenty years ago, standing confused in a wine shop, needing exactly one piece of information to feel like he could move forward.
Most of us never go back and talk to that person. We document what we built instead of designing for who's arriving.
The Dinner Ended, The Problem Didn't
We finished the last pour around ten-thirty. He recommended a bottle to take home. I bought it without knowing what it was, purely because the way he'd handed me information for three hours had built enough trust that I didn't need to know. I'd call that a conversion, technically.
The bottle's still on the counter. I'm saving it for when I finish migrating the first of those three APIs. Seems like the right pairing.
Key Takeaways
- API design is a decision surface, not a documentation exercise — the question is what someone needs to take the next correct step, not how to explain everything you built.
- Getting-started legibility matters more than reference completeness, and most teams have the ratio completely backwards.
- You've forgotten what it felt like to not know your own system. That amnesia is the root cause of most bad interfaces.
- Good design builds trust fast enough that the user acts before they have full information — and that's a feature, not a gap.