When AI writes documentation that needs another document to explain it, we’ve optimized the wrong thing.

The Reader-First Principle: Optimize for readers, not writers.

Every engineering team is writing more documentation than ever before.

Ironically, fewer engineers are actually reading it.

AI has made writing documentation almost effortless. The unintended consequence is that we’ve stopped asking a simple question:

Who is this document actually for?

Too often, the answer is: the AI that generated it.

Documentation that starts as an AI conversation often becomes a transcript of that conversation — complete, polished, and incredibly difficult for anyone else to consume.

That’s the wrong optimization.

Technical documentation isn’t an archive of everything we discussed. It’s a communication tool that helps another engineer understand what they need to know as quickly as possible.

Engineers don’t read documentation. They interrogate it. They’re looking for answers, not chapters.

The Bottleneck Moved

For years, we complained that engineers didn’t write enough documentation.

Now they do.

Or more accurately, AI does.

Architecture Decision Records, RFCs, migration plans, onboarding guides, design documents — what once took hours now takes minutes.

At first, this feels like a breakthrough.

But we’ve confused making documentation easier to produce with making knowledge easier to consume.

Here’s what actually changed.

Before AI:

  • Writing was expensive.
  • Reading was expensive.

Because writing required effort, engineers naturally filtered information before documenting it. Only the information that mattered made it into the final document.

Today:

  • Writing is almost free.
  • Reading is still expensive.

The filtering step has disappeared.

Instead of asking “What does the next engineer actually need to know?”, we ask AI to capture everything because generating another page costs nothing.

But someone still pays.

Every future engineer who opens that document pays with their time and attention.

The cost didn’t disappear.

It simply moved from the writer to the reader.

The Conversation Trap

Here’s the pattern I’ve seen repeated over and over.

An engineer spends an hour working with an AI assistant.

They explore ideas.

Reject alternatives.

Discover edge cases.

Refine designs.

Challenge assumptions.

Eventually they arrive at a good solution.

Then comes the final prompt:

“Generate the documentation.”

The AI faithfully captures everything that happened during the conversation.

The result is polished.

Professional.

Comprehensive.

And completely optimized for someone who already participated in that conversation.

Future engineers didn’t.

They don’t need every question that was asked, every alternative that was rejected, or every implementation detail that was debated.

They need to understand what was built, why it was built that way, and what they need to know to work on it safely.

Somewhere along the way, we’ve started confusing documenting the solution with documenting the thinking process.

Those are different documents for different audiences.

The Documentation About Documentation

The moment I realized we had a problem was almost funny.

An AI generated a large technical document.

It contained architecture diagrams, implementation details, design decisions, alternatives, assumptions, risks, and future improvements.

Everything you’d expect.

Then someone realized the document had become too long.

Nobody wanted to read it.

So they asked the AI to generate…

…another document.

Not a summary.

A guide explaining how to read the first document.

Read that again.

We now have documentation whose complexity requires additional documentation just to navigate it.

The obvious question isn’t “How should I read this?”

It’s “Why was it written this way in the first place?”

If your documentation needs a user manual, the documentation has already failed.

How to Avoid This Trap

AI is an incredible writing assistant, but it shouldn’t be the final author.

Before publishing AI-generated documentation, ask yourself:

  • Would someone who wasn’t part of the AI conversation understand this in five minutes?
  • Is every section necessary?
  • What can I remove without losing meaning?
  • Does this help someone make a decision or complete a task?
  • If this document needs a summary — or worse, another document explaining how to read it — why not improve the original instead?

Documentation exists to reduce cognitive load, not to preserve every thought that led to a solution.

Use AI to organize your thinking.

Use AI to challenge your assumptions.

Use AI to improve your writing.

Use AI to edit ruthlessly.

But don’t confuse more words with better communication.

Remember the Reader-First Principle:

Optimize for readers, not writers.

The best technical document isn’t the one that contains the most information.

It’s the one that helps the next engineer understand the system, make a decision, and get back to writing code.

Because if your documentation needs another document to explain it…

…you’ve already lost.

How is your team using AI for documentation? Have you found ways to keep documentation concise and reader-focused, or are you seeing the same trend? I’d love to hear what’s working — and what isn’t.