Tom’s mouse hovered over the refresh button with a twitch that felt like it belonged to a man twice his age. He wasn’t a systems architect. He wasn’t a database administrator. He was, quite simply, a man who loved heirloom tomatoes and had spent the last 43 hours trying to explain that passion to the internet. But the internet wasn’t listening because his site was down, and the knowledge base he’d been scouring for the last 13 minutes was currently explaining the intricacies of horizontal scaling and load balancer health checks. He just wanted to know why his page wouldn’t load. He felt a bead of sweat roll down his neck, a physical manifestation of the digital wall he’d just hit. The text on the screen looked like English, but it felt like a locked door. It was documentation written by the gods of the machine for other gods, and Tom was just a guy with a spatula and a dream.

We pretend that documentation is about transfer of information, but it’s usually about ego. Or, at the very least, it’s about a profound lack of imagination. When a developer sits down to write a help guide, they aren’t thinking about Tom. They’re thinking about the elegant way they solved the 203 unique edge cases that popped up during the build. They are writing a love letter to their own intelligence, and the customer is merely an accidental voyeur. It’s a tragedy of perspective. I’ve seen this play out a thousand times in mediation rooms where the ‘truth’ is buried under layers of jargon that nobody actually wants to unwrap. I actually caught myself talking to the succulents in my office this morning, explaining the concept of ‘cognitive load’ as if the plants cared. It’s a habit. We talk to hear ourselves. We write to prove we know. We rarely write to be understood by someone who doesn’t already know what we’re talking about.

The Documentation Gap and Subtle Exclusion

This is the documentation gap. It’s the space between what the expert knows and what the novice needs, and currently, that space is filled with 133 broken links and a lot of condescension disguised as ‘technical precision.’ We build these incredibly powerful tools-hosting platforms that could power a small nation-and then we hand the keys to a food blogger with a manual written in ancient Greek. It’s not just inefficient; it’s an act of subtle exclusion. It tells the user: ‘If you don’t know what a CNAME record is without googled it, maybe you don’t belong here.’

I remember mediating a conflict between a CTO and a Head of Marketing at a firm that had just lost 33% of its user base during a migration. The CTO kept pointing to the ‘Migration Wiki’ as proof that they had done their jobs. The Wiki was 23 pages of pure, unadulterated technical brilliance. It was also completely unreadable to anyone who hadn’t spent the last 13 years in a server room. The Marketing Head was vibrating with a specific kind of rage-the kind you get when you’ve been told you’re the problem for not understanding a manual that was never meant for you. I had to step in and remind them that the user isn’t an obstacle to the technology; the user is the only reason the technology exists. If the documentation doesn’t bridge that gap, it’s just a very expensive diary.

The Empathy Deficit

I’ve made this mistake myself. Once, I tried to explain a conflict resolution framework to a couple in the middle of a screaming match using a 13-point diagram on a whiteboard. I was so proud of my internal logic that I failed to notice they had stopped listening 3 minutes into the presentation. They didn’t need a framework; they needed to feel like I understood why they were hurting. Documentation is the same. It needs to start with an acknowledgment of the user’s state of mind. When Tom is searching for ‘why is my site slow,’ he is usually in a state of mild panic. He’s worried about his brand, his income, and the 403 people who might be trying to read his recipe for gazpacho. Giving him a diagram of server architecture is like giving a drowning man a lecture on fluid dynamics. It’s technically relevant, but it’s practically useless.

There is a contrarian reality here that we hate to admit: the people who need the documentation the most are the ones we consider the least when we write it. We write for the ‘power user’ because they speak our language. They give us the dopamine hit of a shared understanding. But the power user rarely needs the manual. They can figure it out through intuition or a quick peek at the source code. It’s the Toms of the world-the non-technical creators, the small business owners, the hobbyists-who are the lifeblood of the web. And we are failing them by refusing to translate our expertise into empathy. We are so afraid of being ‘imprecise’ that we become incomprehensible.

Conversations, Not Manuals

This gap is where the frustration lives. It’s where the churn happens. It’s where people give up on their dreams because they can’t figure out how to point a domain. When you look at the resources that actually work, they don’t look like manuals. They look like conversations. They anticipate the ‘stupid’ questions that aren’t actually stupid at all-they are just the foundational questions that experts have forgotten they ever had to ask. For example, when someone is trying to navigate the complexities of modern hosting without a degree in computer science, finding a guide that speaks their language is like finding water in a desert. Resources like Woblogger serve this exact purpose, translating the high-level technical noise into something a creator can actually use to build their business. It’s about removing the friction, not adding more layers of ‘expertise’ for the user to climb over.

I often think about the first time I tried to fix my own plumbing. I found a video by a guy who clearly knew everything there was to know about copper pipes. He spoke for 23 minutes about the chemical composition of flux. I didn’t need to know about flux chemistry; I needed to know which way to turn the wrench so my basement wouldn’t flood. I ended up calling a professional and paying $373 for a 13-second fix. That plumber didn’t lecture me on flux. He just showed me the valve. Technical documentation needs more ‘valve-pointers’ and fewer ‘flux-experts.’

The Choice Between Clarity and Completeness

We have this strange obsession with completeness over clarity. We think that if we don’t include every single possible variable, we’ve somehow failed as engineers. But for the user, a 1003-page manual is the same as no manual at all. It’s a psychological weight that screams ‘You aren’t smart enough for this.’ And that’s a lie. Most people are plenty smart enough; they just don’t have the time to learn a second career just to run a website. The documentation gap is a choice. We choose to prioritize the integrity of the system over the experience of the human using it.

I’ve been caught talking to myself more than once lately, mostly because the world feels like it’s becoming increasingly fragmented into ‘those who know’ and ‘those who have to figure it out.’ As a mediator, my job is to close those gaps. But in the digital world, the gap is widening. We are building faster, more complex systems, but our ability to explain those systems to a layperson is regressing. We are hiding behind automated bots and AI-generated help articles that are just rehashed versions of the same confusing manuals. It’s a feedback loop of frustration.

The Beginner’s Mindset

If we want to fix this, we have to start by admitting that we are bad at it. We have to admit that our expertise has blinded us. We need to hire people who don’t know how the system works to write the documentation for it. If they can’t figure it out, the documentation is broken, not the person. We need to value the ‘beginner’s mind’ as much as we value the ‘senior architect’s experience.’ Because at the end of the day, a tool that no one can figure out how to use isn’t a tool-it’s a paperweight.

Tom eventually gave up on that knowledge base. He didn’t fix his site that night. He went to bed feeling like a failure, wondering if he should just go back to writing his recipes in a physical notebook where the only ‘server’ was his kitchen table. That’s the real cost of the documentation gap. It’s not just lost revenue; it’s lost potential. It’s the ideas that never get shared because the barrier to entry was a wall of jargon that no one bothered to tear down. We can do better. We have to do better. Documentation shouldn’t be a test of intelligence; it should be a map to success. And maps are only useful if you can actually read them while you’re lost.

The Final Question

Does the language we use to help others actually provide a path, or is it just a mirror for our own vanity?