Baptism (#10)
How Drowning in Technical Details Makes Us and Our Articles Better
I was lost.
Not in the poetic sense, drifting, dreaming, or staring out the window. I mean lost. Real, panic-inducing, neck-deep-in-the-wiki lost.
The API was unfamiliar and undocumented. The engineer who built it was OOO, and the ticket simply read, “Can you write something up for this?”
I tried. For hours. I traced calls. I mapped endpoints. I reverse-engineered a Postman request like it held the secrets of the cosmos.
Still, nothing. No clarity. Just more tangles.
And then, somewhere between the stack trace and the swagger file, something clicked. One term snapped into focus. Then a second. Then the logic behind the whole thing opened up like a submerged door, visible only once you’d gone under long enough to see it.
That’s when I remembered: this is how it works.
We drown. And that’s what saves us.
Why Some Docs Fall Flat
Technical documentation doesn’t fail because of bad grammar or poor formatting. It fails when the writer doesn’t understand the product.
We’ve all read docs that feel like they were written from the outside — perhaps accurate, but hollow. They explain what the feature does, but not why it matters. They parrot terms but don’t translate meaning.
This is the trap: as technical writers, we try to stay dry. We skim the surface of the water and hope that’s enough.
It’s not.
The best documentation doesn’t skim. It plunges.
Baptism Isn’t a Surface-Level Ritual
In the Christian tradition, baptism is more than a symbolic bath. It’s death by drowning — followed by resurrection.
In Romans 6, Paul explains the parallelism of baptism. When someone enters the waters, she joins Christ in his death. When she rises, she shares in his life. New life — with clarity and direction — is impossible without the descent into confusion and chaos. Renewal requires submersion.
You can’t learn to breathe again until you’ve gone under.
For instance, consider the Ethiopian eunuch in Acts 8. This man knew the Scriptures but couldn’t see their meaning — not until Philip found him, walked with him, and baptized him. He rose from the water rejoicing, not only because he changed, but because he understood the truth clearly. Submersion equipped him to understand what had previously been a mystery.
Technical writing demands the same descent. Submersion comes before clarity.
What the Research Says
This isn’t just a metaphor. Cognitive science backs it up.
A 2011 study in Instructional Science found that learners who struggled through "desirable difficulties" — like parsing dense technical material or tackling a complex system — retained more and understood more deeply than those given oversimplified content from the start.
The effort itself creates comprehension. Confusion, it turns out, is not a detour. It’s the path.
This has direct implications for how we approach our work. Writers who avoid the deep end never develop the understanding they need to guide others through it.
Sink First, Then Write
So how do we apply this?
It starts with a shift in mindset. Stop trying to master the system before you get messy with it. Let yourself flounder. Let yourself be confused. Let yourself drown.
Then work your way to the surface — with answers.
Here’s how that looks in practice:
Enter the Product. Don’t just read the spec. Use it. Break it. Trigger the errors. Chase down logs.
Trace the Stack. Follow the logic all the way down. Even if you don’t understand it yet, let the questions surface.
Ask the Dumb Questions. They’re usually the right ones. They expose assumptions and reveal architecture.
Rebuild From the Bottom. Once you understand the bones, you can build scaffolding for the reader. That’s where structure meets clarity.
This kind of writing doesn’t start with an outline. It starts with immersion. It’s not clean or linear, but it’s the only way to emerge with insight that actually helps users.
From Chaos to Clarity
When I finally submitted the article I mentioned earlier, I didn’t just explain the endpoints. I mapped a mental model. I defined each term in relation to what came before it. I gave the reader a handhold in the same place I’d slipped.
I was only able to do this because I was willing to drown.
I no longer saw the product as fragmented. The chaos had a logic. The tangle had a shape. And in wrestling with it, I didn’t just learn the system — I learned how to parse clarity from the chaos.
I came out of that process with sharper instincts, deeper empathy, and a steadier hand for the next time I found myself in deep waters.
Let It Change You
There’s one final truth about baptism that matters here: when you rise, you’re not the same.
This applies to us as writers.
Every time you dive into something opaque, technical, or disorienting, and make it clear, you become a better writer. You sharpen your intuition and pattern recognition. You gain empathy for the reader who’s still underwater.
And then you do it again.
So here’s the job:
Don’t hover on the surface.
Don’t fear the deep.
Sink. Struggle. Stay there.
And when you come up, write like someone who knows what it feels like to drown — and what it takes to breathe again.