Old Misconceptions, New Reality

Sunday afternoon. The app is basically done. The last milestone finished while I was at church, tests are passing, everything's deployed. My wife needs to run a couple of errands before our trip on Monday, so I'm sitting in the car in a parking lot, waiting.

And I'm thinking: this thing doesn't have any documentation.

In the traditional world, documentation is the thing everyone agrees matters and nobody wants to do. Broccoli of software engineering. You know you should do it, you know it helps. But end of a sprint when you're exhausted and the code works and the client's happy, writing docs feels like punishment. Gets pushed to "later" and later never comes. Six months later someone new joins the team, spends two weeks figuring out something they could've learned in an afternoon.

I've been guilty of this my entire career. Every engineer has.

I'm sitting in the parking lot with nothing to do and a VM still running that just finished the last milestone. Pull up the phone, tell Claude: let's do documentation. Overview, quick start guide, comprehensive docs for both audiences. Give me everything.

Claude asked clarifying questions. Good ones. Where does this live? In the app or separate? What level of detail? I said give me everything — overview, quick start, full reference. Cost to me for being thorough was literally zero. Two months ago that sentence would've been insane.

It laid out three stories for the documentation work, I approved them, and it started coding. I put my phone down and waited for my wife.

The Math That Changed

Think about what just happened. I generated comprehensive docs for an entire application from the passenger seat of my car. No IDE. No files. No writer to brief. Described what I wanted, answered two questions, it went to work.

In the old world, you write it yourself, which eats up days and yanks you out of whatever you're actually building. Or you hire a technical writer, which means briefing them on the codebase, reviewing drafts, endless back and forth. Or most commonly you just skip it, ship without docs, and nobody talks about it.

Documentation doesn't get written because the cost has always been too high for what feels like a non-urgent task. There's always something more pressing. Another feature. A bug. A demo. Everyone knows docs matter, but they never feel urgent enough. So they lose.

Agentic development breaks that. When generating docs costs "a couple minutes of direction from your phone," everything changes. Suddenly you can afford to do it. Actually, you can't afford not to.

What I Actually Delivered

When I sent the email to the team Monday morning, it didn't just have a URL and credentials. It had a full documentation suite built into the app. An overview of what the system does. A quick start guide that gets you going in five minutes. Detailed reference docs for the admin users and the API consumers.

The client didn't ask for docs. They expected a prototype. They got a prototype with docs. Good docs. Not placeholder good. Useful docs written by something that actually understood the code.

Because Claude understood the code. It wrote the code. Knew every endpoint, every data model, every business rule. Spent the weekend building all of them. Didn't need to be briefed. It was the codebase.

The Bigger Point

This incremental cost thing won't leave my head. When doing the right thing costs almost nothing, you just do it. Comments, tests, documentation. It all gets done because there's no reason not to.

But there's something deeper here that I keep coming back to. In traditional development, everyone operates under a comfortable fiction: certain things are "easy." Documentation? Just write it up. Admin screens? Those are straightforward. User management? Vanilla. Seed data? Throw it in. We'll knock that out in a sprint.

Except we never do. The "easy" stuff is what kills timelines. The client assumes it's simple because it sounds simple. The PM budgets a sprint. The engineers know better but don't push back hard enough. Five sprints later you're still building the "vanilla" admin console that was supposed to take a week. Every engineer reading this just nodded.

Agentic development is the first time in my career where the assumption actually matches reality. When the client says "can you just add documentation?" the answer is genuinely yes — from a parking lot, on my phone, before my wife gets back from the store. When they want five admin screens for things that currently live in the database, that's an afternoon, not a quarter. The gap between what people think should be easy and what is easy has finally closed.

That's what this parking lot moment really represents. Not just documentation at zero incremental cost. It's proof that the old misconception — "this should be easy" — isn't a misconception anymore.

All the stuff we've skipped for years because it was too expensive or tedious is suddenly free. The products are better because the AI doesn't have friction. Doesn't get tired. Doesn't deprioritize the boring stuff. Doesn't push docs to "later."

My wife came back, bags in hand, asked what I'd been doing. I said writing documentation. She gave me that look all engineer spouses have and said, "On your phone? In the car?"

Yep. In the car.

← Back to Blog