You Are Not the Show
The documentation profession is losing focus at exactly the moment when focus matters most.
This post is part of the Per the docs article series. Links to the rest of the series are at the end of this piece.
Your docs should not be trying to win Miss Congeniality.
The best documentation in the world is invisible. Not friendly. Not engaging. Not warm or witty or conversational. Invisible. The user finds what they need, does what they came to do, and moves on without once thinking about the person who wrote the words that got them there.
That is the craft. That is the whole job.
And somewhere along the way the profession started forgetting it.
The Engagement Problem
Walk into any technical writing conference and you will hear the same conversation. How do we make our documentation more engaging? How do we improve the user experience? How do we write in a way that feels human?
These are not bad questions. But they are the wrong questions.
The moment a technical writer starts optimizing for personality rather than clarity, they have lost the plot.
Those are Rob Hanna’s words. He is the CEO of Precision Content and he has spent decades working with organizations that cannot afford documentation failure. Banks. Insurance companies. Life sciences. Software companies operating at scale.
The product is the show. The writer is not. The user did not pay for the manual. They paid for the product. And all they want from the documentation is to be left alone with the information they need to use it.
This is not a call for cold or robotic writing. Clarity is not the enemy of warmth. Precision is not the enemy of humanity.
But there is a difference between writing that respects the user’s time and writing that tries to entertain them. And the profession has been sliding toward entertainment at exactly the moment when precision has never mattered more.
What the Labs Proved
Rob does not argue from theory. He argues from data.
His team at Precision Content takes a client’s worst documentation. The installation guide everybody hates. The procedure nobody can follow. The reference material that generates the most support tickets. They rewrite it using a structured methodology rooted in the principles Robert Horn established in the 1960s. Chunked. Labeled. Relevant. Consistent. Every information type in its right place.
Then they bring real users into a usability lab.
The before and after is not subtle. With one client, a major organization whose employees depended on internal documentation to serve customers, error rates dropped from thirty percent to five. Time to answer dropped dramatically. The delta, multiplied across the number of employees, the number of work hours, and their salaries, translated into a number that made leadership sit up straight.
But the numbers were only the beginning.
Rob’s team records the sessions on video. They measure time to answer and accuracy. They ask users how they felt about the experience. And then they use AI to analyze the prosody of the recordings. Not what users said. How they said it.
The results were striking. As users worked through the old documentation, the emotional signal was consistent. Frustration. Confusion. The kind of low grade anxiety that comes from not being able to find what you need when you need it. One participant, standing at a service counter with a customer waiting, audibly struggling to locate a piece of information, captured in a single moment what the profession has been inflicting on users for decades.
Then the same users worked through the restructured content.
The emotional signal shifted. Confidence. Relief. The quiet satisfaction of finding the answer exactly where it should be, in exactly the form it needed to be in, without having to think about the person who put it there.
Nobody complimented the writing. Nobody noticed it at all.
That is the goal. That is the standard.
And now AI has entered the room.
What Happens When Documentation Tries Too Hard
When a technical writer mixes information types, adds personality where structure is needed, and optimizes for tone over clarity, something specific happens.
The content becomes ambiguous.
For a human reader ambiguity is uncomfortable but navigable. They slow down. They reread. They ask a colleague. They cut a support ticket. The feedback loop is slow but it exists.
For an AI agent ambiguity is catastrophic.
AI does not slow down when it encounters unclear documentation. It does not reread or ask a colleague. It reasons forward from whatever it has, fills the gaps with plausible extrapolation, and produces an answer that sounds confident regardless of whether the underlying information was clear enough to support it.
This is not a failure of the AI. It is a failure of the documentation.
Robert Horn proved in the 1960s that information has a natural structure rooted in how the human brain actually processes knowledge. Six fundamental information types. Procedure. Process. Principle. Concept. Fact. Structure. Each one has a shape. Each one has a purpose. And when they get blurred, when a procedure starts reading like a concept, when a fact gets buried in a principle, comprehension breaks down.
AI is independently rediscovering those same six patterns because they are real. Because structure is not a stylistic preference. It is how information actually behaves when it is built to be understood.
Which means documentation that ignores Horn’s principles is not just harder for humans to use. It is harder for machines to reason about. And in a world where AI agents are acting on documentation at scale, automatically, without the human pause that used to catch errors before they compounded, that matters enormously.
The friendly, engaging, personality driven documentation that feels like such an improvement over the dry technical manuals of the past is, in many cases, exactly the kind of content that causes AI to hallucinate most confidently.
“The documentation that tries hardest to be noticed is the documentation that fails most quietly.”
The Invisibility Is the Craft
There is a version of this argument that sounds like it is asking technical writers to make themselves smaller. To disappear. To accept invisibility as their lot.
That is not the argument.
The invisibility is the ambition. It is the hardest thing to achieve in this craft. Every word in service of the user’s goal. Every structure in service of the user’s comprehension. Every decision made not for the writer’s expression but for the reader’s success.
That requires understanding how information actually works. How the human brain processes a procedure differently from a concept. How a label changes the speed at which someone finds what they need. How consistency across a document set reduces cognitive load in ways that add up over thousands of interactions.
Rob’s usability labs prove this is not philosophy. It is measurable. The emotional signal changes when documentation is built the right way. Confidence replaces confusion. Relief replaces frustration. And the user moves on without noticing the writer at all.
That is mastery. Not invisibility as failure. Invisibility as the highest possible standard.
And in the age of AI, when documentation is no longer just being read by humans but being ingested by machines that will act on it at scale, that standard is no longer aspirational.
It is existential.
What Needs to Change
The profession is under pressure from outside. Companies are cutting technical writing teams. AI is being positioned as a replacement. The knowledge layer that writers have spent decades building is being treated as expendable overhead.
But there is also pressure from inside that the profession needs to reckon with.
If we are going to make the case that technical writers are essential to the age of AI, we have to be honest about what essential actually means. It does not mean engaging. It does not mean friendly. It does not mean visible.
It means clear. It means structured. It means built for the human and the machine that comes after them.
The product is the show. The writer is not.
Know the difference. Master it. And then make the case, loudly and without apology, that the people who have spent their careers understanding how information actually works are the most important people in every AI strategy being built today.
Because they are.
And it is time we said so.
Previous article: Nick Galinski, “Don’t Turn Off Your Brain”
Next article: Brandi Hopkins, “Auditing the Gaps: A content analysis approach for inherited docs”
See the full list of participants and articles: https://blog.jillshaheen.com/per-the-docs-2026-04-gaps/
Disclaimer: Each article in this series is written and owned by its respective author. The views, opinions, and experiences shared belong solely to the individual writer and do not represent the perspectives of other participants or their employers (past or present).