Why Documentation Is So Hard (And What 30 Years of Failures Taught Me)

The Documentation Struggle Is Real (And We’re All In It Together)

Let’s be honest about something: Documentation is brutally hard to get right.

After 30+ years of writing docs that ranged from actively harmful to occasionally useful, I’ve realized we’re all fighting the same battles: tight deadlines, massive scope, constantly changing requirements, and the impossible task of explaining complex systems to people with vastly different backgrounds.

The humbling truth? I’ve written plenty of terrible documentation. We all have. Usually not because we didn’t care, but because the constraints were impossible.

The “Aha” Moment That Changed Everything

We had a problem at Adobe: developers were drowning in Page Builder setup complexity, and our support channels were flooded with the same basic questions. The traditional approach meant writing detailed documentation about directory structures, file templates, and configuration patterns, then hoping developers could piece it all together.

But then I had a different thought: What if instead of explaining how to build the scaffolding, we just built the scaffolding for them?

So I created pbmodules—a CLI tool that generates complete starter modules with a few simple prompts:

npx https://github.com/commerce-docs/pbmodules.git

The tool walks developers through creating extension modules or custom content types with guided prompts. Within minutes, they have a fully functional starter module with all the boilerplate code, directory structure, and configuration files in place.

The results? Support questions dropped 90%. But here’s the exciting part: the developer community grew stronger. With setup friction gone, developers focused on creative solutions and started helping each other instead of just trying to get started.

Turns out, when you eliminate the busywork, developers can focus on the actual creative problem-solving. Who knew?

The Three Laws of Documentation That Actually Work

After stumbling onto what makes documentation transformative, I’ve boiled it down to three laws that separate life-savers from paperweights:

Law #1: Clarity Is King (But Simplicity Is Queen)

The misconception: Simple means dumbed-down.
The reality: Simple means distilled to its essence.

At Schlumberger, writing for 100+ global developers on oil & gas systems, I learned something crucial: Clarity transcends language barriers. When your documentation might be the difference between a successful drill and a very expensive hole in the wrong place, you get really good at being clear. Fast.

The secret? Start simple, then layer in complexity as understanding grows. Think documentation onboarding, not documentation dumping.

Law #2: Static Documentation Is Where Engagement Goes to Die

My discovery: Interactive elements don’t just improve documentation—they transform it completely.

The magic happens when you give developers:

• Live code examples they can break and fix
• API playgrounds that show real responses to real requests
• Interactive tutorials that feel like guided adventures, not homework
• Visual diagrams that make abstract concepts click into place

Why it works: You turn passive readers into active learners, and active learners actually retain what they learn.

Law #3: Context Is Everything (And Your Structure Probably Ignores It)

Using frameworks like Diátaxis changed how I think about documentation architecture. Developers need different things at different times:

• Tutorials when they’re exploring (“Show me what’s possible”)
• How-to guides when they’re problem-solving (“Just tell me how to fix this”)
• Reference when they’re looking stuff up (“Where’s the parameter list?”)
• Explanation when they need to understand (“But why does it work this way?”)

The killer insight: The same information organized differently can be the difference between developer success and developer rage-quit.

Understanding the Developer’s Reality (And Why Context Matters)

The reality: Developers are problem-solvers under pressure, context-switching between complex systems while deadlines loom.

That comprehensive 47-page setup guide we worked so hard on? Despite our best intentions, it becomes a barrier when someone just needs to solve one specific problem quickly.

Great documentation respects developer reality by:

• Getting to the point faster than a developer loses patience
• Providing multiple entry points for different skill levels
• Anticipating common WTF moments before they happen
• Creating confidence through examples that actually work

How to Measure Success (Hint: It’s Not Page Views)

Forget vanity metrics. The real measures of documentation success are:

• Support ticket volume going down—fewer people are confused
• Developer onboarding time shrinking—learning becomes faster
• API adoption rates climbing—barriers disappear
• Developer satisfaction scores rising—frustration drops
• Community contributions increasing—people finally understand enough to contribute

These metrics tell the real story: Are you helping, or just checking the “we have docs” box?

The Future Is Already Here (And It’s Smarter Than Your Current Docs)

As AI reshapes everything, technical writers aren’t becoming obsolete—we’re becoming experience architects. We’re designing entire ecosystems that adapt, learn, and evolve.

The next wave of documentation will:

• Adapt to individual learning styles—everyone learns differently
• Provide just-in-time guidance—right information, right moment
• Integrate with development workflows—help where developers actually work
• Learn from community interactions—and get better over time

The Never-Ending Story

Here’s the thing about great documentation: It’s never finished. It evolves with technology, grows with the community, and adapts as we learn more about what actually helps developers succeed.

After three decades, I’m more excited than ever. We’re finally moving beyond “here’s how it works” toward “here’s how to make it work for you.”

The ultimate goal remains unchanged: Create those magical “aha” moments where complexity becomes clarity and potential becomes reality.

Your Turn

Got documentation horror stories, success stories, or questions that keep you up at night?

The best insights come from shared experiences and honest conversations about what works (and what spectacularly doesn’t).

After all, we’re all trying to help each other figure this stuff out—and that’s more fun when we admit we don’t have all the answers.

---

Next up: I’m planning to share some real horror stories from the documentation trenches. Because nothing teaches you what works like watching what spectacularly doesn’t.