Generative AI has been hailed as the cure for tedious tasks — and few chores inspire as much collective groaning as documentation. The promise is tempting: offload the drudgery, keep your team in flow, and let the machine tidy up the mess. But here’s the catch: AI doesn’t just automate work, it scales the behaviours we feed it. If those behaviours lean on optics over substance, the result is polished nonsense dressed as clarity.
This isn’t about blaming the tool. It’s about how professionals, under pressure, lean into behavioural shortcuts that feel efficient in the moment but metastasise into dysfunction down the line. When documentation is treated as a box-tick exercise, the polish is mistaken for proof.
Scenario: Lorem Ipsum in a Suit
Situation
A product manager, already stretched thin, is asked to document a late-night feature release. His head is still in sprint chaos, but the deadline looms. To protect his flow — and avoid yet another hour of clerical slog — he pastes rough bullet notes into a GPT and tells it to “make this into documentation.”
Impact
The result looks immaculate: headings, technical jargon, neatly formatted paragraphs. It looks more professional than anything he could write at 1 a.m. So no one questions it. The team files it away without review, comforted by the veneer of polish. Six months later, when a live outage forces engineers to troubleshoot the same feature, the documentation collapses under scrutiny — it reads like lorem ipsum in a suit.
Tension
Now under pressure, the PM is forced to confront not just the outage but his own credibility. The team expects guidance; all he can offer is filler text that obscures the very edge cases they need. This isn’t just embarrassment — it’s reputational damage. His authority as the “archivist” of the feature is on the line, and the stakes are professional, not personal.
Approach
With the clock ticking, he has to reverse-engineer what the AI “meant” from his original notes, pulling in developers to reconstruct intent from code commits and Slack fragments. The shortcut has become a sinkhole — every unspoken assumption now demands excavation. What was meant to save time ends up consuming far more, under far worse conditions.
Resolution
The irony lands cruelly: AI delivered exactly what it was asked for — polished nonsense. By mistaking formatting for fidelity, he planted a time bomb that exploded months later. Minutes “saved” at the point of writing metastasise into days of lost productivity, frayed trust, and institutional scar tissue.
The Mirage of Polish
Humans have a cognitive weakness: we trust things that look good. Psychologists call it cognitive ease — if something feels fluent and easy to process, we assume it’s true. In documentation, this bias is catastrophic. The PM’s team saw tidy headings and assumed substance. It wasn’t laziness, it was behavioural wiring. The smoother something looks, the less likely we are to question it.
This bias compounds under pressure. Late nights and looming deadlines make teams hungry for any signal that the job is “done.” The neat AI-generated document provided that signal — it looked more professional than a tired human could produce, so it sailed through unchecked. But in reality, it was noise masquerading as signal. The words flowed, but the meaning was hollow.
Here’s where Goodhart’s Law bites: when a measure becomes a target, it ceases to be a good measure. “Polish” became the target — the team wanted something that looked like documentation, rather than something that functioned as documentation. Once polish was mistaken for proof, true clarity disappeared. AI didn’t create the illusion, it scaled it with machine efficiency.
The mirage is seductive because it offers relief. Everyone feels a momentary release — the page looks finished, the job looks complete. But polish without substance is a trap. It rewards optics over reality, and the cracks only appear when the system is under strain.
The Cost of Assumptions
The PM assumed AI could fill in the gaps of his bullet points. The team assumed polish equalled quality. Together, those assumptions compounded into dysfunction.
What actually happened was a signal vs. noise collapse. Documentation’s job is to preserve signal: the intent, logic, and edge cases future readers will need. Instead, AI amplified the noise of vague inputs and spat it back as something that looked professional.
Unchecked assumptions are always expensive. Here, they triggered a live outage response with no reliable map to follow. Every missing detail became a landmine under pressure.
Rebuilding Under Fire
By the time the team realised the docs were useless, it was too late. They had to rebuild the documentation from scratch, in crisis mode. Slack messages were dredged up, commits were combed through, tribal knowledge was begged from exhausted developers.
In engineering, there’s an old maxim: inspection is not optional. What isn’t reviewed at creation will be reviewed later, usually under far worse conditions. This is the debt metaphor at work: clarity deferred is clarity borrowed — and the interest rate compounds in crisis.
AI was never the villain here. The villain was the assumption that responsibility for clarity could be delegated away. Used as a collaborator, AI could have accelerated the PM’s thinking, highlighted gaps, and structured his notes. Used as a dumping ground, it became a liability waiting to detonate.
Conclusion
If we keep mistaking polish for clarity, we’re not documenting — we’re planting time bombs. The next outage, the next handover, the next audit will be where they go off.
AI should be embraced, not feared. But embracing it means treating it as a teammate that scales our clarity, not an escape hatch from responsibility. When professionals sharpen their inputs and keep review loops intact, AI magnifies substance. When they don’t, it dresses up nonsense in a suit and calls it done. The choice is ours: scale idiocy, or scale clarity.
Behavioural Principles
Polish Isn’t Proof
-
Optics vs. Substance
Formatting ≠ fidelity. Just because it looks professional doesn’t mean it’s useful. -
Goodhart’s Law
When polish becomes the target, true documentation quality disappears. -
Cognitive Ease
Humans mistake “easy to read” for “true.” AI amplifies this bias. -
Signal vs. Noise
Documentation’s job is clarity of intent. AI can dress up noise to look like signal. -
Inspection is Not Optional
Systems fail when review is skipped. Trust demands verification. -
Deferred Clarity = Debt
Minutes “saved” by skipping substance become hours lost in crisis.
