Sophie, our Product Manager, had that look. You know the one — when someone’s trying to solve a puzzle that shouldn’t exist.
We were in a routine demo of our e-commerce checkout flow, the kind of meeting that usually ends with everyone nodding and moving on. Our prototype was gorgeous. Every pixel in place, every interaction smooth. The demo ran like clockwork.
But Sophie was staring at her laptop, scrolling through customer support tickets.
“I don’t get it,” she said, breaking the satisfied silence. “Henrik keeps failing at checkout, but it works perfectly here. If our API throws payment errors, why can’t I see them in our documentation?”
That’s when it hit me. We’d built a beautiful lie.
The Comfortable Fiction of Happy-Path Testing
Our API documentation was like a restaurant menu that only shows pictures of perfect dishes — never the soggy chips or burnt edges that real customers sometimes get.
Meet our cast of characters:
Emma lives in central Amsterdam. She has iDEAL banking, multiple saved cards, and her postcode gets next-day delivery for everything. When Emma shops, the internet loves her back.
Henrik is a university student in rural Finland. His Nordea card gets declined for mysterious cross-border reasons, shipping to his address takes two weeks, and half the products he wants are “not available for delivery to Finland.” Henrik’s shopping experience is an obstacle course.
Marcel runs procurement for a mid-size company in Lyon. He needs bulk discounts, SEPA transfers, and someone from accounting to approve anything over €500. The e-commerce world wasn’t built for Marcel’s French procurement regulations.
Our documentation only knew how to be Emma. It had never met Henrik or Marcel.
The €75,000 Documentation Problem
Here’s what we discovered: Henrik wasn’t just failing at checkout. He was costing us serious money.
Every time Henrik’s card got declined for a GDPR-related restriction we hadn’t documented, someone called customer service. Every time his Finnish address triggered an error we’d never tested, we lost a sale and gained a support ticket.
The math was brutal. We were spending 48 hours in meetings trying to understand problems that should have taken 30 seconds to reproduce.
Our beautiful documentation had become an expensive fiction.
The Fix: When Documentation Meets Reality
So we did something simple that felt radical. We put Henrik, Emma, and Marcel directly into our API documentation.
Now, when Sophie opens our docs, she sees a sidebar with three buttons. Click “Henrik,” and suddenly the same checkout API that worked perfectly for Emma starts throwing real errors: “Payment method not available in Finland.” “Shipping delayed due to customs requirements.” “Product restricted under EU regulations.”
It’s not just different data — it’s different reality. Henrik’s button makes the API slower (rural Finnish internet), pickier (Nordic banking restrictions), and more honest about what doesn’t work across the Single Market.
The testing environment stopped being a demo reel and became a truth machine.
What We Learned About Building for Real People
The change was immediate. Sophie could finally see what Henrik saw. Our engineers could debug GDPR edge cases without playing 20 questions with customer service. Our support tickets for checkout issues dropped by 41%.
But the bigger lesson was about who we’d been building for. Emma is real, but she’s also easy. She has fiber internet, SEPA compatibility, and lives where everything ships quickly. Building for Emma feels like progress because everything works.
Henrik is real too, but he’s inconvenient. His limitations expose every assumption we’ve made about how European shopping should work. Building for Henrik feels like problem-solving because nothing is guaranteed across 27 member states.
The beautiful, Emma-optimized checkout that looked so good in demos was actually a wall that kept Henrik out. Our documentation had helped us build that wall by making it invisible.
The Bigger Picture: When Perfect Becomes the Enemy of Good
This isn’t just about e-commerce or APIs. It’s about a common management trap: optimizing for the ideal customer while ignoring the real ones.
Every business has an Emma — the customer who makes your metrics look great and your demos sing. Every business also has a Henrik — the customer who reveals where your product actually breaks down across the complexity of the European market.
Most teams build documentation like they’re writing the owner’s manual for a car that only drives on perfect German autobahns. They document the happy path because it’s clean, predictable, and makes everyone feel competent.
But your customers don’t live on perfect roads. They live in Henrik’s Lapland, where the internet is slow and the banks have different rules. They work in Marcel’s Lyon, where nothing is simple and everything needs approval under French commercial law.
Three Questions That Changed How We Build
Before we ship anything now, we ask:
Does this work for Henrik? Not in theory — in practice, with his slow connection and strict Nordic banking requirements.
Can Sophie test the Henrik scenario herself? Without scheduling an engineering deep-dive or hoping GDPR compliance works.
What does failure actually look like? Not the sanitized error message, but the frustrated user experience across different EU regulations.
These questions changed how we think about everything from feature specs to marketing copy. Emma shows us what’s possible. Henrik shows us what’s necessary across the European Single Market.
The day our documentation started telling the truth about Henrik was the day we stopped building for the customer we wished we had and started building for the customers we actually serve across 27 different regulatory environments.
That’s when our perfect prototype stopped lying and started working.
Your documentation isn’t just instruction manual — it’s a mirror. Make sure it’s reflecting the right reality across all your markets.
More to come…
I’ll dig into the evolution of our API and its ripple effects on how we think about design systems.
Want the rest of the story? Join me for the next one.
#ProductStrategy #CustomerExperience #TechnicalDocumentation #EuropeanMarkets #ProductLeadership #APIDesign #UserCenteredDesign #GDPR #SingleMarket