The garage is what I kept looking at. The opening at street level seemed to drop back farther than a single level of parking should allow. I sat there wondering whether I was looking at two stacked levels underneath the house. I don’t know enough about the city’s building limits to say whether that’s even possible. After thinking about it, I decided I was probably looking at a vertical car-stacking lift, a system that lets one garage opening hold twice the cars it appears to hold. Noe Valley has enough wealth concentrated in three-story Edwardians that this kind of luxury home improvement isn’t much of a stretch.

I’d been in a meeting in Silicon Valley earlier that morning about content operations for a tech writing team. The longer I watched, the more my brain started making connections between what I was seeing and what we’d discussed earlier — that’s just how my crazy brain works, jumping between unrelated things until sometimes, if I’m lucky, something clicks.

As I watched the improvements being made to prepare the house to withstand an earthquake it struck me that using this metaphor might be a useful way to help organizations understand why they need to think about retrofitting their content for AI.

Read more

Researchers at Ericsson were testing retrieval-augmented generation (RAG) against technical documents. One of their discoveries was that keywords appearing closer to the beginning of a sentence were retrieved by AI tools with high accuracy. Keywords appearing later in sentences were harder for AI to retrieve accurately.

Before The Model Answers Anything

The paper, Observations on Building RAG Systems for Technical Documents (PDF download at end of article), was written by Sumit Soman and Sujoy Roychowdhury. The researchers tested technical info from IEEE wireless networking specifications and a battery terminology glossary — reference documents, not how-to step-by-step instructions. They examined factors including chunk length, retrieval method, definitions, and keyword position.

Their keyword-position findings:

1. Keywords closer to the beginning of a sentence are retrieved with high accuracy.

2. Keywords appearing later in a sentence were more difficult to retrieve.

Subscribe now

Read more

Because I am who I am, I’d ask him to define “everybody.” I’d ask whether it included me (it usually didn’t); not because he meant to exclude me, but because he’d never actually said what he meant. He’d said something that pointed toward an explanation and assumed the pointing 👉🏾 was enough.

It wasn’t.

After the relationship ended, I went looking for an explanation of my own. I wanted to understand what was happening in our miscommunication.

So, I ordered a stack of books about ambiguity.

The books approached the topic in the context of linguistics, law, business, ethics, and cognition, not technology. Partway through reading them, I started recognizing a pattern; how people evaluate whether our docs, or an AI answer, is any good.

People who rely on implicit communication — the “everybody knows” move — create the conditions for miscommunication without meaning to. That was obvious to me once I made the connection between ambiguity and understanding that several of the authors touched on. But because of the way my brain jumps from one tangentially-related topic to another, I began to wonder if same implicit-versus-explicit gap in documentation might help (at least partially) explain why AI answer engines produce so-called hallucinations?

Read more

According to the client, during a string of security incidents this year the tool started giving incorrect instructions that made things worse. For example, the tool told the team to isolate a compromised server using an API parameter that had been retired months earlier. It also walked a customer through re-enabling an encryption setting that the engineers had phased out for compliance last year. And, in another case, it pointed a customer toward what looked like a standard access shortcut — but was not. Instead, the customer was instructed to utilize a leftover authentication bypass built for a sales demo and never removed from the system.

What The Investigation Found

The client told me their engineering team’s first theory was the oh-so-obvious one: the model was hallucinating.

The engineering crew was wrong. After a little detective work, the team discovered that the theory didn’t hold up once someone checked what the AI had retrieved against what was true. To be clear, the information in the hallucination-laden AI generated text was true once-upon-a-time. But, when things changed with the product, that documentation was never updated. Tracing it back to the source turned up technical documentation files that had been sitting there, unmaintained, for quite a while.

Upon closer inspection, they found:

• the retired API parameter still listed in a publicly available integration guide nobody had updated

• the reasoning behind a compliance change that was only once discussed in a Slack thread between two engineers who’d never migrated it to the wiki the AI used as source content — and who both no longer worked at the firm

• the authentication bypass sitting in the codebase with no comment marking it temporary

• the architecture diagrams the model relied on pointing to repositories that had long-since been deleted

On its own, that’s a documentation debt story.

How The AI Reasoned From What It Found

All of the information accessed by the AI was, at least partially, accurate. The facts were fine. It was the absence of explicit cues in the source content and the model’s reliance on that content that led it to generate inaccurate answers.

That’s an inference failure, not a retrieval failure.

Handed the exact same content, a human cybersecurity tech writer likely would’ve stopped to pause and ask perhaps questions of the underlying information. Experienced folks whose day-to-day work provides them with knowledge those with lesser experience lack, likely notice when something looked off, is out-of-date, or otherwise, potentially wrong. It’s background work most of us do constantly without paying much attention to it.

The AI retrieved the same clues as the human cybersecurity tech writer and did not stop to pause and ask questions of the content. It moved straight from “this exists in a document” to “this is the instruction,” with nothing in between.

The Role Nobody Replaced

The client told me something else about that team. Before any of this, they’d had a reviewer everyone relied on — let’s call her Betsy, since her real name isn’t mine to share.

“Everyone relied on her because she was so good at it,” the client told me.

Betsy was, in their words, always the person who’d say, “That doesn’t look right.”

She retired recently. Nobody replaced her with someone who had the same eye for detail. Her responsibilities got split across the rest of the team instead, so proofing and review responsibilities became something everyone was expected to own a piece of — rather than something one dedicated person owned.

She wasn’t simply catching typos. Betsy’s value came from context, product knowledge, and years of experience layered on top of ordinary editing — the kind of background that lets someone recognize when something is off even when nothing is technically wrong. The client’s regard for her was so high that I started thinking of her as the queen of that function. Nobody worried about coverage while she held that role, because she was there.

And then she wasn’t.

Replace Betsy with a system that reads the same docs at machine speed, and the habit of stopping to ask whether something looks right disappears along with her. The documentation debt didn’t get worse. It got a new kind of reader — one with no instinct for stopping to check for accuracy. 🤠

It attempts to evaluate organizational preparedness across seven pillars. The strange thing is, technical documentation isn’t one of them. That sent me looking for where, exactly, technical documentation should fit into Microsoft’s model, and whether an organization can call itself AI-ready while the documentation feeding its answer engine isn’t.

What Microsoft Means By AI Readiness

Microsoft’s AI Readiness Assessment evaluates whether an organization has the strategy, governance, data, people, infrastructure, and model-management capabilities to adopt AI securely and at scale.

It’s built around seven pillars:

1. Business Strategy

2. AI Governance & Security

3. Data Foundations

4. AI Strategy & Experience

5. Organization & Culture

6. Infrastructure for AI

7. Model Management

The assessment runs on multiple-choice / multiple-response questions. Completing it produces an overall score, category-level recommendations, and links to related guidance. Signed-in participants can export their results to a CSV file.

This assessment approach seems like a reasonable way to size up organizational readiness. Companies looking to put AI to work need leadership support, real safeguards, usable data, decent infrastructure, and people who know WTF they’re doing.

But there’s a question hiding inside those seven pillars that Microsoft never asks directly:

What knowledge is the AI actually going to use when someone asks a question (and expects an accurate answer) about how our products work?

Read more

Then I realized something was different. Those files mostly help systems discover or process information that’s already there. llms.txt exists to help AI systems understand our documentation.

For decades, tech writers have made editorial decisions about what customers should know. We decide which concepts deserve an explanation, which procedures belong (or don’t) in our product docs, and which content should be retired because it no longer reflects reality.

Today, many publishing platforms automatically generate a document whose audience isn’t your customer at all. Instead, it’s AI.

This Isn’t Just Another Generated File

An llms.txt file is often described as a guide for AI systems. That’s accurate, but incomplete. It’s much more than that. You can think of it as a summary of what your organization considers important enough for AI to read first.

Depending on how your documentation platform generates it, the file may point to product overviews, API references, tutorials, SDKs, migration guides, code examples, and other documentation. An AI system can use that information to build an initial understanding of your product long before it retrieves content from any individual page.

That’s a different editorial function than a sitemap.

👉🏾 A sitemap says, “These pages exist.”

👉🏾 An llms.txt file effectively says, “Start here.”

Automatic Doesn’t Mean Curated

Recently, I examined the llms.txt file for a public API documentation site. Nothing in it was confidential. Every page it referenced was already public.

What surprised me wasn’t the content. It was how much easier the file made it to understand the product.

Instead of exploring the documentation one section at a time, I could immediately see the major APIs, supporting guides, integration points, and product organization. The documentation had been distilled into a machine-readable map.

That’s exactly what the file was designed to do.

The question is whether that map reflects an editorial decision or simply the default output of a publishing platform.

Those aren’t the same things.

An automatically generated file may include deprecated documentation, legacy APIs, archived migration guides, experimental features, or transitional content simply because those pages are still public. The software doesn’t know which content best represents your product today. It only knows what we tell it.

This Is An Editorial Question

Tech writers are the people who decide how a product should be explained. We choose examples, organize information, and retire obsolete content. We often work with product managers, software developers, support teams, and legal reviewers because we understand that publishing is an editorial process, not a database export.

I think llms.txt belongs in that process. If AI systems are going to use it as a starting point for understanding our documentation, then someone should review what it communicates before its published.

Not because AI shouldn’t read your documentation. Because we should be intentional about what we’re helping it understand.

A New Publishing Checklist

Most documentation teams already review titles, links, examples, screenshots, and metadata before publishing. It may be time to add one more item to that checklist.

👉🏾 Review the documentation we’re publishing for machines with the same care we give the documentation we’re publishing for people.

A publishing platform can generate an llms.txt file automatically. Only we can decide whether it tells the right story about our product. 🤠

Note: The llms.txt specification is evolving through community input. Its GitHub repository provides version control, issue tracking, and public discussion, while a community discord channel gives implementers a place to share experiences, compare approaches, and discuss emerging best practices.

That advice has been retired by Google, but the exact same content model is now being promoted for Answer Engine Optimization (AEO) by a host of others, and I wanted to know whether the new claim is supported by comparable evidence.

What Answer Engine Optimization Aims To Accomplish

AEO is the effort to improve how often and how accurately an organization’s information or brand name appears in answers generated by AI systems. AEO includes AI features in search engines, but it isn’t limited to Google or Bing. It also applies to answer engines that search or retrieve information from the web and use what they find to generate a response.

AEO success can mean several things. Your organization might be mentioned in an answer or your information might be used without attribution. A page might receive a citation or link and someone might follow that link, visit the website, and take a business action.

What I want to know if this: Does organizing content around explicit questions followed by concise answers improve the chances that an AI answer engine will retrieve, use, or cite that content? And is the evidence strong enough to justify changing a website’s content model?

Read more

I had described the same workflow differently in two places. Some of the business rules didn’t become apparent until Claude reached points where the process couldn’t continue without them. Guidance I had developed over time conflicted in subtle ways that I hadn’t noticed because I already knew what I meant, but Claude didn’t.

Each time Claude reached one of those points, we stopped and worked out what the process was supposed to be. Sometimes that meant reconciling conflicting language. Other times we reorganized the information because the structure no longer held. A few problems forced us back several steps.

Looking back, we didn’t spend most of our time building software. Instead, we tried making the work explicit enough that Claude could apply it.

Why Did This Feel So Familiar?

A few weeks later I read a paper from Harvey, makers of AI software for legal pros, about governing AI agents. One sentence stopped me.

“Agents do not change what governance is for. They change where governance happens.”

A few pages later, another passage:

“Before automation can produce consistent results, the underlying process has to be understood, documented, and made repeatable.”

That described what had been happening more clearly than I had.

I wondered whether Harvey was unusual.

Read more

AI is building an understanding of your product. The quality of that understanding depends more on your documentation than many tech writers realize.

Information architecture isn't becoming more important because AI arrived. AI just wandered into a conversation we technical writers have been having for decades.

We choose terminology, define content relationships, create navigation, build taxonomies, declare and apply metadata, and decide where information belongs. Those decisions help people make sense of complex software products.

Reading Andrea Volpini’s recent article about the Perception Graph made me look at our work from a different angle.

What Is A Perception Graph?

According to Volpini, a Perception Graph is the internal model AI builds about a product, organization, or topic after analyzing information from many sources. Instead of remembering documents page-by-page, AI systems develop an understanding of how products, features, tasks, roles, and terminology all fit together. When someone asks a question, it answers from that model rather than from content available in a specific document.

If you’ve ever wondered why AI can explain how several features work together without quoting a specific page, this is one reason.

What Is A Signal Graph?

A Signal Graph is the collection of evidence AI uses to build that model.

Product documentation is part of this graph, but so are product pages, API references, release notes, advertisements, support articles, blog posts, videos, structured data, software review sites, analyst reports, customer reviews, community discussions, white papers, and news coverage. Some sources deserve more trust than others, but all of them contribute signals to the mix that AI utilizes to conjure up responses.

Why Should Tech Writers Care?

While our documentation may be the most authoritative description of our product, it isn’t the only one AI encounters.

Imagine the same capability described as Projects in one of our user guides, Workspaces in a release note, and Teams somewhere else on the web. While human customers usually can work their way out of such content hairballs, AI has to decide whether those various names describe one feature, three different features, or documentation that disagrees with itself.

The same thing happens when our marketing team introduces a new product name before the documentation changes, when release notes describe a workflow differently than the user guide does, or when outdated topics remain online long after the software changed.

Every one of those examples becomes another signal AI uses to generate responses.

What Makes Documentation AI-Ready?

The exact same qualities that help people understand a product also help AI do the same.

👉🏾 Consistent terminology reduces ambiguity
👉🏾 Clear relationships between concepts help AI connect information correctly
👉🏾 Accurate metadata adds context
👉🏾 Well-structured content makes it easier to recognize how ideas fit together

None of those practices were invented for AI. We’ve relied on them for years because they improve understanding.

Why Information Architecture Still Matters

For years, we’ve described information architecture as the discipline that helps people locate the information they need. Finding information, however, is only the first step. Information is only useful when people understand it.

Customers build mental models of our products as they read our docs Those models help them predict what a product will do, recognize patterns, and solve problems they haven’t encountered before.

AI is doing something similar.

That’s what stayed with me after reading Volpini’s article. His terminology is new to me. The underlying idea isn’t.

Tech writers have been helping people build accurate mental models of products for a long time. AI depends on many of the same information design decisions. 🤠

Claude described the company as helping European SMEs make their content AI-ready. That detail wasn’t something I remembered seeing on the product website, so I asked Claude where it came from.

The answer Claude provided was revealing. According to popular AI platform, The Content Forge website is apparently built as a JavaScript application, and, as a result, it couldn’t easily retrieve the rendered page. Instead, it relied heavily on the HTML it could see — including the metadata — the page title, meta description, and Open Graph tags. It treated those fields as evidence and folded the metadata it could see into its explanation of the company.

Metadata Isn’t Just For SEO Anymore

HTML metadata serves many purposes. Some metadata tell web browsers how and where to display content a web page. Other types help search engines index content, control how pages appear when shared on social media, verify site ownership, or identify the preferred version of a page. Other metadata describes what the aboutness of the content on the page.

Read more

We’ve lived with the consequences of outdated content for years. What’s changed today is that those consequences are now much easier to see. Support analytics, customer feedback, self-service metrics, and AI systems now expose information problems that in the past may have remained hidden.

Tech writers have discussed these issues for decades. The costs are simply harder to ignore now.

What Is Documentation Debt?

The symptoms are familiar: outdated procedures, obsolete screenshots, broken links, duplicate content, conflicting instructions, and knowledge base articles that no longer match the product.

Documentation debt rarely arrives all at once. A feature ships before the technical documentation is updated. A subject matter expert leaves the company. Ownership becomes unclear. Teams focus on creating new content while older information slowly falls out of date.

The work doesn’t disappear; it accumulates.

Many Tech Writers Already Understand Technical Debt

Many of us have spent years working alongside software teams that discuss technical debt.

Developers use the term to describe shortcuts, deferred maintenance, aging code, or design decisions that eventually make software harder to maintain. Teams understand that the cost does not disappear simply because the work was delayed.

Documentation works much the same way.

When updates are postponed, maintenance is deferred, or ownership becomes unclear, organizations accumulate documentation debt.

Both forms of debt represent deferred maintenance.

Technical debt affects the software itself. Documentation debt affects the information people rely on to use, support, maintain, purchase, and troubleshoot that software.

Engineers encounter technical debt in the codebase. Tech writers run into documentation debt through support tickets, failed searches, outdated procedures, and frustrated users.

Technical debt is widely recognized because it affects schedules, budgets, and engineering productivity. Documentation debt affects support costs, customer experience, operational risk, and the reliability of information systems.

Support Costs Increase

Customers who can’t find accurate answers themselves eventually give up and often contact customer support.

Support teams spend time correcting outdated instructions, explaining product changes, or helping customers navigate procedures that no longer match the product. The same questions appear repeatedly because the underlying information problem remains unresolved.

Organizations invest in self-service because they want customers to solve problems on their own. When users stop trusting the docs (or the answers generated by AI systems with access to them), those investments lose much of their value.

Higher ticket volumes, longer resolution times, and repeated support requests are often symptoms of documentation debt.

User Frustration Grows

Users rarely complain that our docs are outdated. Instead, they say the product is confusing. They struggle during onboarding, abandon self-service, and contact customer support because they can no longer find the answers they need. Sometimes they conclude that the company is difficult to work with and look to one of our competitors.

To the user, bad documentation is part of the product.

When instructions fail, screenshots no longer match the interface, or search results lead to obsolete content, confidence begins to disappear. Customers may blame the software, the support team, or (more than likely) the company itself.

Documentation influences the customer experience long before someone contacts support.

Notable quote:

“A mismatch between the copy used to describe a service and the choices that a user can actually make is an easy way to lose trust.”

— Lexie Kane, Nielsen Norman Group

When Information No Longer Matches Reality

Problems arise when people rely on information that no longer matches the systems, products, or policies they use every day.

Incorrect procedures, obsolete warnings, inaccurate configuration instructions, or outdated policy information can affect compliance, security, safety, and business operations.

Internal documentation creates similar risks. Employees may rely on procedures that no longer reflect current systems or company policies.

Every organization depends on accurate information to help employees and customers make decisions.

AI Makes Documentation Problems Easier To See

In some organizations, AI has become the equivalent of a very impatient customer. It encounters outdated content, conflicting instructions, and missing information immediately.

AI assistants often rely on product documentation, knowledge bases, customer support articles, and internal data repositories to answer questions. When those sources contain outdated or conflicting information, the answers they generate often reflect those same problems.

Generative AI has made documentation problems much harder to ignore. It frequently exposes information problems that support teams and customers have encountered for years.

Some organizations first recognize their documentation problems when an internal assistant or customer-facing chatbot gives users the wrong answer. Investigation often reveals that the underlying content itself is unreliable.

Why Tech Writers Should Care

Technical writers understand that information requires maintenance. Most of us have encountered procedures nobody follows, features that changed without notice (or were never implemented as planned), and content that remained untouched for years because no one owned it.

What has changed is who experiences the consequences.

Support leaders are seeing rising ticket volumes. Customer success teams are hearing complaints. Product managers are struggling with adoption problems, and executives are worrying about the risks associated with inaccurate AI answers.

These concerns create opportunities for tech writers to participate in conversations that extend beyond publishing schedules and content deliverables.

Documentation quality is a business issue.

What Technical Writers Can Do

Tech writers may not own every content decision, but they often recognize documentation debt before anyone else does. Many writers have encountered knowledge base articles that nobody has reviewed in years, procedures tied to features that no longer exist, or instructions that support teams quietly work around every day. The challenge is often not identifying the problem. It is helping the organization understand which problems matter most and why they should care.

Find The Biggest Problems First

Many organizations don’t know how much outdated content they maintain.

Content audits can reveal pages that have not been reviewed in years, procedures associated with retired features, broken links, duplicate information, and articles connected to recurring support cases. Support data, search analytics, and usage information often point directly to the places where stale content creates the greatest frustration.

We don’t have to fix everything at once. We need to identify where inaccurate information creates the greatest consequences.

Start Where The Pain Is

Not every piece of documentation deserves the same level of attention.

Customer onboarding information, installation instructions, troubleshooting content, frequently viewed knowledge articles, and safety or compliance information often have the greatest impact on customers and support teams. Content associated with recurring support cases may also deserve immediate attention.

A relatively small amount of content often creates a disproportionate amount of user frustration.

Make Maintenance Part Of The Process

Documentation debt accumulates when maintenance becomes nobody’s responsibility.

Review schedules, named content owners, release-driven content reviews, and regular audits help prevent information from quietly becoming obsolete. Software development teams routinely plan for maintenance work. Documentation teams can benefit from the same discipline.

Use AI To Find Problems

AI can help identify documentation debt as well. Doc teams can use AI tools to locate duplicate content, identify inconsistent terminology, compare procedures against current interfaces, and detect references to retired features.

Human review remains essential, but AI can help surface information problems that might otherwise remain hidden.

Tech writers may not control product roadmaps, staffing decisions, or organizational priorities, but they do understand how information breaks down over time and where those failures affect customers, employees, and support teams.

That perspective is increasingly valuable.

Documentation Supports Business Operations

Organizations often think of documentation as something that gets written, published, and moved aside.

The people using that information experience it differently.

👉🏾 Employees depend on it to do their jobs.
👉🏾 Customers use it to solve problems.
👉🏾 Support teams rely on it to answer questions.
👉🏾 AI systems increasingly use it to generate responses.

When the information no longer matches reality, the consequences show up throughout the organization.

Technical debt became an accepted business concern because organizations learned that ignoring it became expensive. Documentation debt is no different.

Many organizations still treat documentation debt as a publishing problem rather than a business problem. It’s time for that to change. 🤠

The criticism is fair. Large language models are known to invent facts, confuse details, and produce answers that sound convincing even when they are wrong. What interested me more was the assumption underneath the slogan. The comparison only works if people are reliable.

Tech writers spend enough time interviewing subject matter experts to know that isn’t always true. Ask several people how a product feature works and you may hear several explanations. One engineer describes the original design. Another explains how the system behaves today. Support remembers the workaround customers use. Product management recalls a decision that was never documented.

Nobody intends to mislead anyone, yet the facts often arrive tangled together. Much of the work of technical writers involves sorting through those competing accounts.

Human Hallucinations Are More Common Than We Admit

Chris’s post assembled several examples that are uncomfortable precisely because they involve ordinary people rather than obvious bad actors.

A YouGov survey found that 2 percent of Americans said they firmly believe the Earth is flat. Another 7 percent said they were unsure about the Earth’s shape. Among younger adults, the uncertainty was even higher.

A separate Economist/YouGov poll found that 12 percent of Americans agreed that the Moon landing was staged.

Related reading: Conspiracy vs. Science: A Survey of U.S. Public Beliefs

The so-called Mandela Effect offers another example. In a 2022 YouGov survey, 40 percent of Americans said they had shared a memory with others that many people remembered differently or believed to be false. When asked about specific examples, 61 percent remembered the children’s books as the “Berenstein Bears,” even though the books have always been published as the “Berenstain Bears.”

The same survey found that 28 percent of respondents considered parallel universes or alternate dimensions a plausible explanation for these shared memories.

These examples are easy to dismiss because they seem unusual, but memory errors appear in situations with much higher stakes. Eyewitness testimony remains one of the most persuasive forms of evidence presented in court. Yet the Innocence Project reports that eyewitness misidentification played a role in roughly 69 percent of convictions later overturned through DNA evidence.

One of the best-known cases involved Jennifer Thompson, who deliberately studied her attacker’s face so she could identify him later. She selected Ronald Cotton from a lineup, testified against him in court, and remained convinced she had identified the correct person. Cotton spent more than a decade in prison before DNA evidence established that another man had committed the crime.

Why Organizations Write Things Down

Organizations create documentation for many reasons. New products need instructions, APIs need references, and customers need help completing tasks. Over time, documentation also becomes a record of decisions, product behavior, terminology, and procedures that people may remember differently or forget altogether.

Most documentation teams eventually discover procedures that nobody follows, product behavior that differs from the manual, and explanations that change depending on who is asked. Generative AI did not create these problems.

When an AI system produces an incorrect answer, the mistake appears immediately. Human errors often move more slowly. They become outdated procedures, undocumented assumptions, conflicting explanations, and organizational folklore that survives long after the product changes.

Every tech writer has heard someone begin a sentence with, “We’ve always done it this way,” only to discover that nobody can explain why.

People And AI Make Different Types Of Mistakes

People are forgetful. We combine separate events into a single memory, and rely on assumptions, repeat information we heard years ago, and sometimes remember what we expected to happen instead of what actually happened.

Language models fail differently. They predict likely responses from patterns in training data and retrieved information. They may combine facts incorrectly, invent missing details, or generate plausible explanations that lack evidence.

Neither Humans Nor AI Systems Deserve Automatic Trust

It turns out that people and language models need many of the same things: good information, enough context, and a way to check whether an answer is supported by evidence.

Most of us have been in the meeting where three people remember the same decision three different ways. Eventually someone finds the ticket, the email, or the requirements document, and the argument ends.

Tech Writers Already Understand The Problem

Must we choose between reliable humans and unreliable AI? I hope not.

Anyone who has worked in documentation for very long has encountered the software engineer or product creator who explains a feature with complete confidence, only for testing to reveal that the product behaves — ahem — differently.

Every doc team eventually finds a procedure that nobody actually follows. Support teams have their own version of this problem, repeating explanations they conjure up that might have matched the product several releases ago but no longer do.

AI gives employees another place to get answers, but somebody still has to check whether those answers match the product, the policy, and the documentation.

What This Means For Tech Writers

Technical writers regularly walk into situations where different people remember the same event differently. One person recalls the decision, another remembers the exception, and somebody else insists the whole thing changed two releases ago. Eventually we have to sort through the emails, tickets, release notes, and meeting minutes to figure out what actually happened.

That work becomes even more important as AI systems begin answering questions alongside documentation, support teams, and subject matter experts.

Organizations have always operated with incomplete information. People remember meetings differently, repeat outdated explanations, and hold onto decisions that quietly changed years ago. Documentation helps reduce some of that confusion, even if it never eliminates it completely.

AI now participates in many of the same conversations that once belonged entirely to coworkers, support staff, and subject matter experts. That puts more pressure on the underlying information. Procedures, release notes, requirements, and product documentation increasingly serve both people and machines.

For tech writers, the work is familiar. Somebody still has to determine what is true, what changed, and which version belongs in the documentation. 🤠

A recent review of banking developer portals by Pronovix, a consultancy that specializes in developer portals and developer experience, suggests that assumption may be creating new problems. The company evaluated the portals of eleven major banks to see how well they support AI-assisted discovery and evaluation.

Banking was a useful test case because financial institutions have spent years investing in APIs, developer portals, and open banking initiatives. The industry has had plenty of time to refine how it presents technical information to developers and partners. If gaps in context, discoverability, and content relationships appear in environments this sophisticated, chances are good they’re unlikely to be unique to finance.

As I read through the findings, I kept noticing how many of the issues sounded familiar. Missing context. Weak connections between related content. Technical information separated from business meaning.

Tech writers have been dealing with these challenges for decades.

Why Are Some Developer Portals Hard For AI To Understand?

Many of the portals reviewed contained substantial technical information. The problem wasn’t a lack of docs. It was that much of the documentation contained information focused on implementation while providing limited context about business purpose.

Many portals explained how a capability worked but spent less time explaining who it was for, what problem it solved, or when someone should use it. That distinction matters because implementation and discovery are different activities.

👉🏾 Someone who already knows which API they need is looking for instructions
👉🏾 Someone evaluating possible solutions is looking for context

Many portals seem to assume site visitors already know what information they need. That works well for implementation, but it works not-so-well for discovery.

What Is The ‘Semantic Gap’ In Technical Documentation?

Pronovix uses the term semantic gap to describe the distance between business language and technical language.

Marketing teams describe business value. Product teams describe capabilities. Technical writers explain how those capabilities are used. When that information is spread across different websites, repositories, and systems, the relationships between the pieces become harder to see.

The result is that readers must connect the dots themselves. Tech writers see this problem regularly. Users care about goals. Product teams too often focus on functionality. The docs we create frequently serve as the bridge between those perspectives.

The review suggests that AI answer engines face many of the same challenges. When use cases, audiences, business outcomes, and technical capabilities are loosely connected, understanding becomes more difficult.

Why Does Content Fragmentation Matter?

The review found that understanding a product often requires gathering information from several sources. A user may need to access one website to understand the business value, another to understand the product capabilities, a developer portal for implementation details, and a support site for troubleshooting help. The content exists, but the relationships between individual pieces are not always obvious.

This observation helps explain why tech writers spend so much time discussing information architecture, metadata, taxonomy, governance, and terminology management. Those practices help establish connections between related content.

What Happens When Important Content Is Hidden Behind Login Walls?

Organizations often place valuable information behind registration forms and authentication barriers. The issue isn’t whether the content exists. The issue is when it becomes available. If important information appears only after registration or authentication, it can’t help visitors understand, compare, or evaluate options during the discovery process.

Does Technical Documentation Influence AI Recommendations?

Documentation is not the only factor that influences whether a product or service appears in AI-generated answers. However, documentation contributes evidence.

When documentation clearly explains capabilities, audiences, use cases, business goals, and implementation details, there is more information available to support understanding. When content focuses almost exclusively on technical specifications and procedures, there is less context available.

Good docs have always explained more than how to complete a task. They help readers understand purpose, relevance, and relationships between concepts.

What The Findings Tell Us

The findings reinforce many principles tech writers already advocate for:

👉🏾 clear terminology
👉🏾 strong information architecture
👉🏾 useful metadata
👉🏾 well-defined audiences
👉🏾 practical use cases, and
👉🏾 content that explains purpose alongside procedure

None of those practices were created for AI. They exist because people need context to understand complex information. The review suggests that AI tools benefit from many of the same signals.

Reading through the findings, it is difficult not to notice how many of the observations map directly to challenges tech writers have been discussing for years. Missing context, disconnected information, inconsistent terminology, and weak relationships between content assets are not new problems. The review simply shows what happens when those problems are examined through the lens of AI-assisted discovery. 🤠

Most discussions about AI costs focus on language models. That’s understandable. Models have names, rankings, benchmarks, pricing pages, and marketing campaigns.

Content gets far less attention. That’s surprising because AI systems spend much of their time looking for information before they generate an answer.

That distinction becomes more important as organizations move beyond experimentation and begin deploying AI-powered support systems, internal assistants, knowledge portals, and agentic search experiences at scale.

Stripe, the online payments company that processes transactions for millions of businesses, recently caught my attention for exactly that reason. The company announced AI usage billing, a capability that charges customers in proportion to what they consume (e.g., tokens processed, compute seconds, API calls, agent actions) rather than a flat fee.

The announcement wasn’t about model quality. It was about consumption. How many tokens were used? Which application consumed them? How should those costs be allocated? How should they be recovered? By whom?

Once organizations can see AI consumption, they’re eventually going to ask why some AI-powered experiences cost more to operate than others. In many cases, part of the answer may be the content itself.

Why Does Content Ambiguity Increase AI Costs?

Tech writers have always worried about ambiguity because it frustrates readers. AI systems introduce another reason to care.

Suppose a procedure says:

“Approve the request after validation completes.”

Most people working in that environment can probably figure out what’s happening. They know who performs the approval and they understand what validation means. They probably know what event signals validation completion.

AI systems don’t share that background knowledge.

If the role, condition, or triggering event isn’t documented, the AI system often searches for that information elsewhere. As documentation repositories grow, those searches become more expensive. The answer may already exist, but the system may retrieve multiple documents, compare competing explanations, and evaluate additional context before it can decide which information to use.

The System Has To Find The Missing Pieces

Many organizations assume AI works like a very fast employee who already knows where everything is. In reality, AI systems spend a surprising amount of time searching, comparing, ranking, and evaluating information before generating an answer.

A user asks a simple question. The retrieval system may pull multiple documents, compare overlapping explanations, evaluate terminology, identify the most likely workflow, and discard information that appears unrelated.

When our documentation is clear, the search narrows quickly. But, when our content contains inconsistent terminology, undocumented assumptions, duplicate information, or missing workflow context, the system often retrieves more material than it otherwise would.

Organizations are beginning to measure that work.

What Does TRACE Have To Do With It?

TRACE stands for Tasks, Roles, Actors, Conditions, and Events. The framework grew out of an observation I’ve encountered repeatedly in documentation reviews: many problems aren’t caused by missing information. They’re caused by missing context.

👉🏾 The task is described, but nobody identifies the role responsible for it.
👉🏾 The workflow is documented, but the triggering event isn’t.
👉🏾 The actor changes halfway through the process without being identified.
👉🏾 The conditions that determine success or failure exist only as assumptions.

Human readers often work around those gaps because they already understand the environment.

TRACE became interesting to me because it highlights exactly the information retrieval systems often go looking for. When tasks, roles, actors, conditions, and events are explicit, the system has stronger clues about what a topic is describing and how it relates to other topics.

Technical Documentation Has Entered the Cost Conversation

For years, tech writers justified structured content using familiar arguments around reuse, consistency, metadata, governance, localization, and maintainability. Those arguments still hold up today.

What’s changing is the audience for the discussion. As organizations start tracking AI consumption, content issues may begin appearing in conversations that previously focused on infrastructure, support operations, and technology spending.

We’ve spent years cleaning up duplicate content, arguing about terminology, and chasing down missing workflow details. Those activities may sound unrelated to AI operating costs. They probably aren't.

Those same issues may also increase the amount of work AI systems perform before it can answer a question.

Five years ago, most conversations about structured content focused on publishing efficiency, governance, and reuse. AI may pull the discussion into a different part of the organization, the people responsible for operating budgets.

Why Tech Writers Should Pay Attention

Organizations are building AI systems on top of documentation repositories, knowledge bases, support portals, and content collections that were never designed for machine consumption. Some of those systems will work remarkably well. Others will consume more resources than expected because the underlying content requires constant interpretation.

We’ve been talking about context, consistency, terminology, and structure for years. If organizations begin tracking AI consumption the way they track cloud spending, those conversations may start happening in different meetings with different stakeholders. 🤠

For years, we tech writers have been trying to explain structured content to people who looked at metadata the way you might look at steamed broccoli. 🥦

Necessary? Maybe. Exciting? Absolutely Not.

Then AI arrived, wrapped in venture capital and optimism, promising to revolutionize the way we work and eliminate our drudgery.

And now, suddenly, organizations are discovering something painful we tech writers have been muttering for decades: Messy information is expensive. 💰

Welcome to the strange new world where unclear docs and inconsistent product information can increase infrastructure spending.

Tokens: The Invoices Nobody Talks About

Let’s start with tokens because the AI industry throws the word around as though everybody understands it.

Every time an AI system:

• reads a prompt

• retrieves documentation

• processes instructions

• accesses a service

• searches for references

• remembers conversation history

• generates a response

…it consumes tokens. And tokens cost money. 💴

At small scale, the costs feel trivial. A chatbot rewrites our awkward email message. A support assistant summarizes a customer support case. Somebody in marketing asks AI to “make this sound more dynamic” and receives three paragraphs that sound like a regional bank trying to flirt.

No big deal, right?

But organizations aren’t deploying AI for one interaction. They’re deploying it everywhere for all sorts of reasons.

• Customer support

• Internal search

• Knowledge retrieval

• Workflow automation

• Developer assistance

• Sales enablement

• Training systems

• Agentic orchestration

That’s where the meter starts spinning.

Related reading: AI can cost more than human workers now

AI Doesn’t Understand Our Documentation

This is important. AI models don’t “understand” our content the way humans do.

Humans are remarkably forgiving creatures. We can infer meaning from terrible prose, missing context, vague terminology, and screenshots that look like they were captured during a small electrical fire 🔥.

AI systems aren’t really understanding anything (in the human sense). They’re processing statistical language patterns and attempting to assemble probable meaning.

Which means ambiguity creates work. And work creates token consumption.

Now imagine the AI retrieves:

• six overlapping procedures

• two outdated workflows

• contradictory terminology

• troubleshooting mixed into conceptual overviews

• outdated screenshots from 2019

• a release note pretending to be task guidance

• an unlabeled warning block that reads like a hostage note

The system now has to process all that material trying to determine what’s actually relevant.

💰 Costs start to rack up quickly.

Retrieval of data costs tokens. Ranking what it found and reasoning across it costs more. Generating an answer adds — you guessed it — more expense.

Then the agent may decide it’s uncertain and retrieve even more content.

Because your documentation repository has become the informational equivalent of a kitchen junk drawer filled with expired coupons, tangled charger cables, mystery batteries, and three keys nobody recognizes but nobody dares throw away.

Agentic AI Makes the Problem Worse

Traditional chatbots were comparatively simple. They answered a question and moved on with their lives.

Agentic AI systems are different.

These systems often:

• interpret intent

• reformulate questions

• retrieve multiple content chunks

• compare sources

• invoke tools

• summarize results

• validate outputs

• retry retrieval

• generate next actions

Every step burns tokens.

And the less explicit your documentation is, the harder those systems must work.

This is where technical writers should become deeply interested in the economics of ambiguity.

Because the AI industry increasingly profits from uncertainty.

The more your content forces AI systems to infer meaning, the more compute gets consumed.

And now companies like Stripe are openly building systems to meter, monitor, bill, and even profit from AI consumption costs.

That’s not science fiction anymore. That’s accounting.
https://techcrunch.com/2026/03/02/stripe-wants-to-turn-your-ai-costs-into-a-profit-center/

The AI industry is quietly transforming tokens into a utility model.

Like electricity.

Or water.

Or those suspicious resort fees hotels add while pretending the hallway Wi-Fi is a luxury experience.

This Is Why Structured Content Matters Again

Technical writers have spent years talking about:

• reuse

• taxonomy

• metadata

• controlled language

• modularity

• governance

Usually while someone from another department asks whether we can “just put it in Confluence.”

Now AI has accidentally made all those conversations financially relevant.

Structured content reduces retrieval waste.

Clear topic types help AI systems distinguish between:

• tasks

• concepts

• references

• troubleshooting

• policies

Consistent terminology reduces ambiguity.

Metadata narrows retrieval scope.

Reuse reduces duplicate processing.

Governance improves precision.

The goal is no longer just helping humans find information.

The goal is helping AI retrieve the smallest amount of information necessary to generate a reliable answer.

That’s token efficiency.

And token efficiency is becoming operational cost control.

PREA Makes AI Work Less

This is where PREA becomes especially interesting.

DITA already gives organizations structural consistency. But structure alone doesn’t always expose operational meaning clearly enough for AI systems.

A topic can validate perfectly while still leaving important relationships implicit.

PREA — Process, Role, Event, Actor — helps make those relationships explicit.

Instead of forcing AI systems to infer:

• who performs an action

• what triggers a workflow

• which actor changes a system state

• when a process starts or ends

…the content tells the system directly.

That matters enormously in agentic retrieval systems.

Without PREA, an AI may retrieve dozens of vaguely related chunks because it’s relying mostly on keyword overlap and statistical proximity.

With PREA-informed content, retrieval becomes narrower and more precise.

The AI reads less because the documentation says more.

That’s the magic.

Not magical in the “wizard sparks and unicorn tears” sense.

More like the deeply satisfying magic of finally labeling storage bins in the garage after years of opening random boxes looking for extension cords.

Every Vague Heading Creates a Tiny AI Tax

This may sound dramatic, but it’s true.

Every ambiguous title.

Every duplicated procedure.

Every overloaded topic.

Every inconsistent term.

Every undocumented workflow transition.

Every “Important Information About Setup” heading quietly increases computational effort.

One isolated retrieval operation costs almost nothing.

Millions of retrieval operations across thousands of users become a budget discussion.

And organizations are going to start noticing.

Especially once finance departments realize AI systems don’t merely consume software licenses.

They consume language.

Technical Writers Are Quietly Becoming Infrastructure People

Nobody entered technical communication dreaming of optimizing inference efficiency.

Yet here we are.

The role is changing.

Technical writers are no longer just producing documentation for human readers.

We’re increasingly designing information environments for machine consumption too.

That means our choices affect:

• retrieval precision

• context size

• inference efficiency

• hallucination risk

• orchestration overhead

• operational AI costs

Which is honestly a bizarre career development.

Somewhere in 1998, a technical writer was carefully adjusting bullet indentation in Microsoft Word while eating yogurt from a desk drawer and worrying about printer drivers.

That person probably didn’t imagine future writers would one day influence enterprise AI infrastructure economics.

And yet.

Here we are.

Because in the age of agentic AI, content isn’t merely communication anymore.

It’s fuel.

And fuel costs money.

Humans do this so naturally that we rarely notice it. Machines don’t.

I was thinking about that while reading a recent LinkedIn post from knowledge graph researcher Benny Cheung. He described the progression from data to taxonomy to ontology to knowledge graphs and argued that organizations that stop too early in that progression are likely to struggle with AI.

The post resonated with me because technical writers have been dealing with parts of this problem for years, although we don’t usually use the same vocabulary.

Organizing Information Isn't The Same Thing As Defining Meaning

Most organizations have plenty of places to store information. They have databases, content management systems, knowledge bases, SharePoint sites, and file repositories.

Storage isn’t the problem.

Cheung points out that a database schema and an ontology solve different problems. A schema describes how information is organized. An ontology describes what something is, how it relates to other things, and what rules govern those relationships.

Many organizations blur those distinctions. They assume that once information is structured, categorized, and stored, meaning somehow comes along for the ride.

It doesn’t. Not even close.

Consider the difference between a content label such as “firmware update” and a description that explains who performs the update, what event triggered it, what conditions must be true before it can begin, and what happens when it succeeds or fails.

👉🏾 One helps identify a topic.
👉🏾 The other helps explain how something works.

For AI systems, those details matter.

Taxonomy Helps You Find Things

Technical documentation teams have spent years building taxonomies. We classify products, features, audiences, document types, and metadata values. That work is useful because it helps people find information.

The challenge is that classification only answers part of the question.

AI systems increasingly depend on structured context, not just text. Knowledge graphs and RDF (Resource Description Framework) represent entities and the relationships between them, while action and process models make it explicit who performs an action, what object is affected, what events or conditions shape a workflow, and how activities connect across a process. That structure helps AI systems retrieve information with context and perform multi-step tasks more reliably.

Those relationships are often scattered across multiple documents or left unstated because human readers can usually infer them. AI systems don’t always infer them correctly or consistently.

That’s where many documentation repositories start to show their age. The information exists, but the relationships are incomplete, inconsistent, or implied.

Why Documentation Can Confuse AI

When people read our documentation, they bring a lifetime of experience to the process. They know that customers and technicians have different responsibilities. They recognize that a setup procedure may not apply during routine operations. They can usually tell when a warning belongs to a specific circumstance rather than every circumstance.

Documentation often depends on that kind of judgment.

Large language models don’t read the way people do. Not even remotely. They generate responses based on patterns and probabilities. When key relationships are missing, the model may connect things that shouldn’t be connected, skip conditions that matter, or assign actions to the wrong person or system.

The result can sound reasonable while being wrong.

That’s one of the reasons I’ve been working on the TRACE framework:

• Tasks

• Roles

• Actors

• Conditions

• Events

The framework grew out of a simple observation. Many documentation problems that affect AI have less to do with missing information than with missing context. The facts may be present, but the relationships between those facts often aren’t.

Tech Writers Are Already Working in This Space

Tech writers routinely define components, describe workflows, document responsibilities, explain dependencies, and identify conditions that affect outcomes.

Most of us think of that as documentation. But, viewed another way, it’s also the work of defining how a system operates.

That’s why I think some organizations are overlooking a valuable source of expertise. They want AI systems that can answer questions across large collections of enterprise knowledge, but they often treat documentation as a publishing function rather than a knowledge-definition function.

The people who understand the relationships are frequently the same people who wrote the documentation.

Why Knowledge Graphs Are Back In The Conversation

Knowledge graphs have been around for years, but many organizations never saw a compelling reason to invest in them. Search generally worked “good enough.”

Generative AI changed expectations. Organizations now want systems that can explain relationships, answer questions in context, connect information across departments, and adapt responses to different situations.

Those capabilities depend on more than retrieving content. They depend on understanding how pieces of information relate to one another.

Knowledge graphs can help with that, but only if the underlying content contains clear relationships. If the source material is ambiguous, the graph inherits the ambiguity.

At some point the AI starts filling in the blanks. What appears to be an AI problem may be exposing weaknesses that have existed in our documentation all along.

A Different Way to Think About AI Readiness

Many conversations about AI readiness focus on models, tools, and infrastructure. Those things matter. But organizations may also need to look at the information itself.

👉🏾 Is operational context explicit?
👉🏾 Are actors clearly identified?
👉🏾 Are conditions documented?
👉🏾 Are workflows connected in ways that a machine can follow without making assumptions?

Those questions sound a lot like documentation questions.

That’s why Cheung’s post caught my attention. It highlights a gap that technical writers have been working around for a long time. As organizations push AI deeper into customer support, training, service delivery, and enterprise search, that gap becomes harder to ignore.

The issue may not be that organizations lack content. It may be that too much of the meaning still lives in the heads of the people reading it. 🤠

Subscribe now

Here’s the problem with that: technical documentation was never primarily about typing sentences. The real work has always been deciding what matters, how information connects, what order things belong in, which warnings will save somebody from catastrophe, and which missing prerequisite is about to turn a software deployment into a small electrical fire in the server room.

AI won’t eliminate tech writing, but it is exposing what tech writing actually is.

The Great Decoupling

For decades, writing and architecture were welded together. If you wanted documentation, someone had to manually draft every sentence. Writing and thinking looked like the same activity because they happened in the same place.

AI broke that relationship.

The easiest way to understand this is to stop thinking about documentation and start thinking about construction.

For years, we were expected to design the blueprint and lay every brick ourselves. Want a 50-page manual? Congratulations. Please hand-place 20,000 words while also managing review cycles, fighting SharePoint permissions, and wondering why the product changed three days before launch and nobody bothered to inform you.

Now AI shows up as an automated bricklayer capable of laying ten thousand bricks a second. That sounds impressive (until you realize what happens when you unleash an automated bricklayer without a blueprint).

Suddenly there’s a staircase leading into a hedge. The bathroom opens directly into the kitchen. A wall suddenly appears across the driveway.

The machine builds quickly. It just doesn’t build intelligently on its own. That’s the real shift. Drafting has become cheap. Architecture has become valuable.

Your Company’s AI Is Only As Smart As Its Documentation

Organizations keep spending on AI while feeding it a digital landfill full of outdated PDFs, random Google Docs, unstructured help articles, inconsistent terminology, duplicate procedures, and seventeen different ways to describe the same button.

AI systems don’t magically create truth. They retrieve information from whatever source material exists. If the source material is a mess, the AI becomes a highly confident confusion machine.

This is why information architecture suddenly matters to executives who previously thought metadata was some kind of skin condition.

Technical writers aren’t just producing content anymore. They’re building the operational knowledge layer that AI systems depend on to function safely.

And honestly, some of us have been trying to explain this for twenty years while being treated like the office people who “make the PDFs prettier.”

The New Career Split

Although my crystal ball 🔮 is cracked (and my psychic powers are limited), I predict tech writing is no longer one profession moving in one direction. It’s splitting into several paths. Four, for now.

The Pure Writer

The Pure Writer isn’t working to generate words with AI. Instead, they’ll focus on the parts of communication lifecycle where human judgment matters most. They’ll create onboarding experiences, conceptual content, narratives, and guidance that require empathy, audience awareness, and deep understanding of human behavior.

It’s measured instead by how effectively they help people learn, make decisions, overcome uncertainty, and build confidence. They’ll be the ones who excel at interviewing subject matter experts (think forensic interviewing), uncovering hidden assumptions, understanding audience needs, and translating complexity into meaningful human experiences.

AI can help generate prose, but it cannot fully replicate judgment, empathy, cultural awareness, or the ability to understand what people are feeling when they encounter information. The Pure Writer focuses on communication as a human craft, creating content that informs, reassures, persuades, and guides people through moments where understanding matters most.

The Augmented Writer

The Augmented Writer operates at the intersection of human expertise and machine-assisted production. This is the high-velocity, high-volume path. Instead of starting with a blank page, they’ll start with a prompt, a source document, or a structured dataset and use AI to generate first drafts at scale. Fast!

Their value isn’t measured by typing speed. It’s measured by throughput, editorial judgment, and the ability to transform raw information into useful content quickly. They review, refine, fact-check, and shape AI-generated output into material that meets organizational standards.

Whether producing release notes, API references, procedural content, summaries, or knowledge articles, they dramatically increase the volume of content that can be created without sacrificing quality.

The Augmented Writer understands both the strengths and limitations of AI. They know when to delegate drafting to the machine and when human review is required. Their role is less about writing every sentence and more about directing, evaluating, and improving a high-speed content production system.

The Content Engineer

The Content Engineer focuses on the structure beneath the content. They aren’t primarily concerned with crafting sentences or refining tone. Nope. Their attention is focused on metadata, taxonomies, content models, schemas, reusable components, and the systems that allow information to move reliably through an organization.

Their value comes from creating highly structured, predictable environments where content can be assembled, reused, translated, personalized, and delivered automatically. They design the frameworks that make scale possible. They’ll ask questions such as:

👉🏾 How should this information be modeled?
👉🏾 What metadata is required?
👉🏾 Can this content be reused across multiple outputs?
👉🏾 How will a machine interpret this structure?

The Content Engineer understands that modern content is no longer just something people read. It is data that must be processed by content management systems, search engines, translation platforms, AI assistants, and autonomous agents. Their work makes those systems more efficient, more reliable, and more scalable.

While others focus on the words, the Content Engineer focuses on the architecture that makes those words usable. They build the pipes that allow information to flow.

The Knowledge Orchestrator

The Knowledge Orchestrator sits at the intersection of human communication and machine intelligence. They understand both what makes information clear, useful, and trustworthy for people, and also, how AI systems, search engines, knowledge graphs, and retrieval architectures consume that same information.

Their value comes from designing and governing the organization’s “truth layer”, the structured knowledge foundation that both humans and machines depend on. They’ll focus their efforts on thinking beyond individual documents and work to improve and maintain how information flows across systems, how knowledge is modeled, how ambiguity is reduced, and how meaning is preserved from source to consumption.

The Knowledge Orchestrator understands that modern documentation has two audiences: humans and machines. They design content ecosystems that support both. They analyze retrieval failures, improve information architectures, establish metadata and terminology standards, and ensure that AI systems can retrieve and apply information accurately and safely.

While others create content or build content systems, the Knowledge Orchestrator ensures that the entire knowledge ecosystem works as a coherent whole. Their responsibility is not simply publishing information. It is creating the conditions that allow people and machines to consistently find the truth.

AI Is Also Reading Your Documentation Now

Many writers still haven’t adjusted to a simple reality: People are no longer your only audience. AI agents read documentation too. Sometimes they act on it.

An AI-powered migration agent may follow your database migration instructions step by step. If your documentation omits a prerequisite, leaves an assumption unstated, or says something vague like “configure as needed,” the AI won’t stop to ask questions. It will continue with whatever interpretation it can construct.

In the past, poor documentation frustrated customers and increased support costs. Now it also can cause automated systems to make mistakes at scale. That changes the consequences of documentation ambiguity.

Ambiguity Is Now a Technical Failure

Technical writers need to understand grounding and Retrieval-Augmented Generation (RAG). The terminology sounds complicated, but the underlying idea is straightforward: AI systems perform better when the source content is clear, structured, and explicit.

When terminology varies from one document to another, when process steps are implied rather than stated, or when important conditions are buried in paragraphs of prose, retrieval systems can surface the wrong information or miss critical information altogether. This is where technical writers become increasingly valuable today.

Many ambiguities (the types we might introduce in our docs) are the kind that people can resolve through experience, context, or conversation. But these same ambiguities are much harder for machines to handle. An experienced employee may recognize that a step is missing or that a prerequisite is implied. An AI system has no such intuition. It can only work with the information it retrieves.

The quality of the answer depends heavily on the quality of the information architecture behind it.

The Skills AI Can’t Hallucinate

Several skills become more valuable as AI becomes more capable. One of them is forensic interviewing.

AI can reorganize and summarize information that already exists. And, it’s quick and fairly accurate at these tasks. However, AI systems can’t reliably uncover information that was never documented. It doesn’t know when a developer skipped a critical step because “everyone knows that.” It doesn’t recognize when an SME assumes background knowledge that new users don’t have.

Much of technical documentation assumes readers will fill in missing context. TRACE, a framework I've been developing for evaluating AI readiness, identifies five elements that are frequently left implied: Tasks, Roles, Actors, Conditions, and Events. The goal is to make operational meaning explicit so information can be interpreted reliably by both people and machines.

That distinction matters because people and machines consume information differently. People can (and do) often infer missing context from experience. Machines can’t do that. If a task, condition, or responsibility isn’t clearly expressed, an AI system may retrieve incomplete information or interpret it incorrectly.

Then there’s accountability.

AI systems don’t worry about consequences. They don’t hesitate before publishing instructions or question whether a warning is prominent enough. Nor do they wonder if a missing prerequisite could create a problem for someone (or something) else downstream.

What they do is generate output.

People (that means us) remain responsible for deciding whether that output is accurate, safe, appropriate, and complete. As organizations rely more heavily on AI-generated content and AI-assisted workflows, that responsibility becomes more important, not less.

The Shift From Drafting To Design

AI is very good at mechanical content production. It can generate first drafts, summarize documents, transform formats, adjust tone, and handle many of the repetitive tasks that consume a writer’s day.

The higher-value work remains firmly human. Someone still has to design the information architecture, establish metadata and taxonomy standards, govern terminology, evaluate risk, identify missing context, and determine whether information is accurate and trustworthy.

This distinction matters because organizations don’t succeed simply by producing more (and more and more and more) content. They succeed when people and systems can find, understand, and apply the right information at the right time. Period.

For many tech writers, that has always been the most interesting part of the work. Understanding complex systems, organizing knowledge, and making information usable requires judgment that cannot be delegated easily. AI hasn’t eliminated that work. If anything, it has made its importance more visible.

The New Center Of Gravity

The arrival of generative AI has not reduced the importance of technical communication. It has changed where the value resides.

For decades, writing and information architecture were tightly coupled. If you wanted documentation, someone had to write it. Today, drafting is becoming faster, cheaper, and increasingly automated. The scarce resource is no longer the production of words. It is the creation of information that can be trusted, retrieved, interpreted, and applied correctly.

Organizations need people who can uncover missing context, reduce ambiguity, model knowledge, establish terminology, govern information assets, and ensure that both humans and machines can understand what the content means.

That work has always existed. It simply lived in the shadow of drafting.

AI has pushed it into the foreground. 🤠

For most of the internet’s history, humans directly interacted with content. We searched, clicked, read, compared, interpreted, and decided what to trust. Websites competed for our attention. Search engines acted as maps that guided us toward information, but humans still visited the original destination.

That relationship is beginning to change.

Increasingly, AI is becoming the layer between humans and information. Instead of navigating websites, people are asking questions. Instead of reading ten links, they are receiving one synthesized answer. Instead of evaluating sources themselves, they are trusting systems to interpret the internet on their behalf.

The shift may sound subtle, but it fundamentally changes the role of content online. Content is no longer just something humans consume directly. It is becoming raw material that machines interpret, summarize, rank, and repackage before humans ever see it.

We are entering the era of invisible content.

The Collapse of the Footnote

In many ways, this transformation is already here. Google’s AI Overviews, ChatGPT, Perplexity, Microsoft Copilot, and other conversational systems are changing how people interact with knowledge. Industry analysts at Gartner have projected that traditional search engine volume is on track to decline by 25 percent as users increasingly migrate toward AI driven conversational experiences.

For publishers, media companies, and enterprise organizations built around discoverability, the implications are structural. The internet is shifting from a referral driven network to an ecosystem increasingly shaped by extraction and synthesis.

As Cloudflare CEO Matthew Prince recently observed while discussing the future of AI search:

“People aren’t following the footnotes.”

To understand the scale of this transition, look at the widening gap between machine crawling and human visiting. A decade ago, search engines crawled websites primarily to guide humans back to original sources. Today, AI systems increasingly consume information without returning meaningful traffic to publishers. According to comments shared publicly by Prince, emerging AI platforms appear to generate dramatically higher crawl to referral ratios than traditional search engines, with extraction metrics for major LLM crawlers scaling into the thousands or even tens of thousands of pages scraped for every user redirected back to a source.

The result is already becoming visible across digital publishing ecosystems. Multiple analytics firms and media organizations have documented significant drops in referral traffic as users increasingly receive summarized answers directly within AI interfaces. But traffic loss is only part of the story. The deeper shift is psychological.

The internet is moving from an environment where humans evaluate information themselves to one where AI increasingly mediates reality for them.

That changes how trust works online.

From Source Literacy to Interface Trust

For years, trust on the internet was tied to visible signals. People trusted recognizable publications, established brands, expert authors, or communities they felt aligned with. Even when misinformation existed, users still had some awareness of where information originated.

AI changes that relationship because it compresses many sources into a single confident response. The original context disappears. Nuance fades. Contradictions flatten. In many cases, even the source itself becomes secondary.

The answer becomes the interface.

This compression also amplifies something psychologists have long studied: automation bias. Humans naturally tend to place greater trust in structured, automated outputs, especially when they appear confident and efficient. Researchers are increasingly examining how the fluency and conversational tone of Large Language Models can create an illusion of authority even when information is incomplete, outdated, or inaccurate.

People quickly adapt to whatever feels easiest, and fast conversational AI fits that pattern well. Once users get used to instant, low-effort answers, going back to slower manual research feels inconvenient, but convenience alone does not guarantee trust: people may prefer the speed while still questioning whether the answer is accurate, complete, or safe.

When humans begin emotionally trusting systems that summarize reality for them, the internet changes from a network of information into a network of mediated interpretation.

The Enterprise Imperative: Content As Machine Infrastructure

This creates an entirely new playbook for organizations far beyond media companies.

For content strategists and information architects, this may become one of the defining challenges of the next decade. We are no longer designing content exclusively for human readers. Increasingly, we are designing it for machine interpretation.

Modern AI systems rely heavily on structured and retrievable information. When organizations use Retrieval Augmented Generation frameworks to connect AI models with enterprise knowledge, the quality of the underlying content architecture becomes critical.

AI systems perform better when information is modular, semantically organized, clearly tagged, and consistently maintained.

If corporate knowledge bases, technical documentation, policies, or support systems are fragmented, inconsistent, or buried inside static files, the AI pipeline begins to weaken. Messy, incomplete, or inconsistent inputs usually lead to unreliable AI outputs because models can only work with the context and constraints they are given. When prompts are vague or poorly structured, the system is more likely to guess, omit important details, or produce inaccurate results. Even sophisticated AI models cannot consistently produce trustworthy outcomes from chaotic source material.

This is why the future of content strategy may depend less on publishing volume and more on governance, structure, and information integrity. The real competitive advantage will not come from generating endless amounts of synthetic content. It will come from building systems that preserve clarity, provenance, consistency, and trust in environments increasingly saturated with machine generated information.

A Premium On Authenticity

Ironically, as generative AI makes text, images, video, and code easier and cheaper to produce, genuinely trustworthy information may become more valuable, not less.

Human credibility, transparent sourcing, and verified expertise become premium.

We are already beginning to see the early foundations of this shift. Initiatives such as C2PA, the Coalition for Content Provenance and Authenticity, are developing technical standards that help verify where digital content originated and whether it has been manipulated. At the same time, organizations are investing more heavily in structured content systems, metadata frameworks, modular authoring models, and governed knowledge ecosystems that can support trustworthy AI experiences at scale.

Practices once considered niche disciplines within technical communication and enterprise documentation are steadily moving toward the center of business strategy.

The internet has always evolved through layers. First came static pages, then social platforms, then algorithmic feeds. AI introduces another layer entirely: interpretation itself.

The biggest change AI brings to our digital landscape is not simply that machines can create content. It’s that humans may increasingly stop seeing where that content came from in the first place, making the invisible architecture behind information one of the most important forms of infrastructure in the AI era.

The conversation about AI often focuses on what machines can create. But the more profound question may be what humans stop doing.

When AI becomes the primary interface between people and information, fewer users visit original sources, compare perspectives, examine evidence, or evaluate context for themselves. Increasingly, those responsibilities shift to the systems that retrieve, interpret, and present information on their behalf.

That makes the future of content larger than a publishing problem or a search problem. It becomes a trust problem.

The organizations that succeed in the AI era will not necessarily be those that generate the most content. They will be those that build the most trustworthy knowledge ecosystems—systems where information is accurate, structured, traceable, and resilient enough to survive multiple layers of machine interpretation.

For content pros, this represents a significant shift in responsibility. Content isn’t simply a communication asset — it’s part of the infrastructure through which people understand reality.

The era of invisible content is not really about content disappearing. It’s about the growing importance of the information architecture, governance, content provenance, and trust mechanisms that remain invisible to users but increasingly determine what they see, believe, and act upon. 🤠

Swaha Bhattacharya is a senior content strategist and technical communicator with over 11 years of experience in enterprise technology. Having worked extensively in structured content, documentation, knowledge systems, and AI-enabled experiences, she writes about the future of content strategy, information architecture, and trust in an increasingly AI-mediated world.

That’s what makes the example a useful teaching aid for tech writers looking to make the tech docs content easier for AI answer engines to process.

The topic highlights a growing problem in tech docs — content that works adequately for humans can still be highly ambiguous when AIs consume it.

Humans are remarkably good at filling in missing context. We infer relationships automatically, and we assume causality. We understand implied actors and unstated conditions because we’ve spent our entire lives navigating incomplete communication.

AI systems don’t actually “understand” any of those relationships. In lieu of understanding, they infer them probabilistically. That distinction matters.

The SimpliSafe topic contains several examples where operational context is implied instead of modeled explicitly. Those gaps create opportunities for retrieval errors, procedural confusion, and AI hallucinations.

The original topic is here: SimpliSafe: Updating Your SimpliSafe System

I evaluated the topic using TRACE, a framework I’ve been developing to identify contextual signals AI systems need in order to generate reliable answers.

TRACE looks for:

• Tasks

• Roles

• Actors

• Conditions

• Events

The goal isn’t to make documentation sound robotic. It’s to reduce ambiguity by making operational context explicit enough that AI systems don’t have to guess.

Here’s where the topic begins to break down.

1. The Actor Is Implied Instead of Explicit

The documentation states:

“Updates will occur automatically after you disarm your system.”

That sounds fine to a human. But who performs the update?

👉🏾 The cloud service?
👉🏾 The Base Station? The mobile app?
👉🏾 The keypad firmware manager?

The actor is missing from the instructions. Often, humans will attempt to infer the answer. AI systems often will invent one.

Before

After

The revised version explicitly identifies the:

👉🏾 actor performing the update
👉🏾 human role involved
👉🏾 triggering condition

That reduces inference dramatically.

2. Conditions Are Mentioned But Not Modeled

The topic references Bluetooth requirements in prose:

“You’ll need to make sure Bluetooth is enabled…”

That sentence contains a critical operational dependency, but it’s buried conversationally instead of treated as a formal condition. AI systems frequently miss this kind of implied prerequisite during retrieval and summarization.

Before

After

This structure makes operational dependencies explicit and machine-readable.

3. Triggering Events Appear In Prose Instead Of As State Changes

The topic explains that updates occur after disarming the system, but it never explicitly models the state transition itself.

That matters because AI systems often flatten event sequences into vague summaries.

Before

After

This version identifies:

• the triggering event

• the resulting system behavior

• the operational sequence

That’s much easier for retrieval systems and LLMs to interpret correctly.

4. Process Boundaries Blur Together

The topic mixes:

• Base Station updates

• Smart Lock updates

• camera updates

• troubleshooting

• firmware behavior

into one broad workflow.

Humans can usually untangle this. AI chunking systems often cannot.

That increases the likelihood of retrieval contamination where instructions for one device or process get incorrectly applied to another.

Before

After

This creates cleaner semantic boundaries for both humans and AI systems.

5. Failure States Collapse Into Generic Troubleshooting Language

The topic says:

“If your system fails to update…”

But that phrase hides multiple distinct failure conditions:

• firmware download failure

• interrupted installation

• unsupported firmware version

• connectivity timeout

• Bluetooth pairing failure

• device synchronization problems

Humans may eventually figure out the difference.

AI systems frequently collapse all of those into generic troubleshooting advice because the documentation never differentiates them clearly.

Before

After

Now the system can distinguish between failure states instead of treating “update failed” as one ambiguous condition.

The Important Thing Here Isn’t That The Documentation Is “Bad”

It isn’t. The topic is fairly typical support documentation. Most tech writers would recognize the style immediately. Many customers probably complete the process successfully.

That’s exactly why this example matters. The docs were written for human interpretation, not AI retrieval and generation.

Humans tolerate implied context extremely well. AI systems don’t. When operational relationships remain unstated, large language models compensate probabilistically.

That’s where hallucinations often begin:

👉🏾 assigning actions to the wrong actor
👉🏾 merging unrelated workflows
👉🏾 skipping conditions
👉🏾 flattening event sequences
👉🏾 inventing causal relationships

The industry keeps talking about “AI-ready content” as if structure alone solves the problem. It doesn’t.

A DITA topic can be perfectly valid XML — see Well-formed XML — while still omitting the operational context AI systems need to generate reliable answers.

That’s the problem I’m working to expose. 🤠

👉🏾 Not because the model is “stupid.”
👉🏾 Not because the AI vendor failed.
👉🏾 Not because Mercury is in retrograde again.

The problem is probably the documentation itself.

Welcome to retrieval contamination. It’s one of those phrases that sounds like a plumbing issue in a pharmaceutical lab, but it describes a very real problem tech writers are about to spend the next several years untangling.

Retrieval contamination happens when an AI system pulls instructions, warnings, conditions, or procedural steps from the wrong source and blends them into an answer that sounds plausible enough to pass casual inspection. The AI doesn’t necessarily invent the information. In many cases, it retrieves real information from somewhere else in our documentation set and applies it to the wrong product, version, role, workflow, or situation.

That’s the important distinction. This isn’t hallucination in the classic sense (there’s no such thing). It’s often contamination through proximity.

And we’re sitting right in the blast radius.

The Documentation Equivalent Of Putting Leftovers In The Wrong Container

You know how someone puts mashed potatoes into the yogurt container and then the next morning you confidently spoon potatoes into your coffee? 😆 Hopefully not — but if something similar has ever happened in your world — it’s like that.

AI systems retrieve content by similarity. They look for patterns, relationships, terminology overlap, semantic closeness, and contextual signals. If your docs repeatedly reuses vague phrases like “press the reset button,” “restart the device,” or “update the firmware,” the system may retrieve procedures from multiple products that happen to look statistically related.

Especially if:

• the metadata is weak

• product names are inconsistently applied

• versioning is at worst, non-existent or at best, sloppy

• our docs assume human readers will “know” which product a paragraph belongs to

Humans use common sense and visual and other sensory-fueled context to separate instructions. AI retrieval systems don’t have that luxury.

To a retrieval engine, these two sentences may look dangerously similar:

“Press and hold the reset button for 10 seconds.”

and

“Press and hold the reset button until the light flashes amber.”

If the surrounding contextual clues are weak, the system may merge nearby fragments into a Frankenstein procedure assembled from multiple devices like some kind of support-ticket centaur.

Read more

👉🏾 Too complicated
👉🏾 Too rigid
👉🏾 Too enterprise
👉🏾 Too many angle brackets
👉🏾 Too old
👉🏾 Too “legacy”

And perhaps most emotionally loaded of all:

“Won’t structure kill our creativity?”

That last one always fascinated me because nobody asks airline pilots whether take-off preparation checklists suppress self-expression. Nobody asks surgeons whether standardized procedures interfere with their artistic vision while someone’s spleen is open on the table. 😷

Meanwhile, tech docs teams using structured content quietly continued doing things their less-structured counterparts struggled to manage consistently: multichannel publishing, large-scale localization, semantic metadata management, content reuse, personalization, governance, and automation.

Because XML never left – at least not in oplaces where leadership understood the business value structure provided.

The funny part is that XML’s roots in Standard Generalized Markup Language (SGML) made some people treat it like historical reenactment software. Mention SGML at a conference and some younger attendees react like you just brought up Mesopotamian irrigation techniques.

And yet, despite all the mockery, structured content systems kept quietly powering enormous documentation ecosystems behind the scenes while the rest of the industry periodically reinvented badly organized content in various ways.

Today, AI has arrived and software engineers, startup founders, and self-appointed “prompt engineers” are wrapping prompts in XML tags because they are learning some of the same lessons we learned years ago:

Computers work better when you stop making them guess.

Somewhere, a senior DITA architect just smiled so hard they startled the cat and pulled a neck muscle.

Related: XML Tutorial from W3Schools

AI Needs More Structure Than People Expect

Large language models are very sophisticated prediction systems. Which means ambiguity creates problems very quickly.

When an AI model receives a giant content hairball comprised of loosely organized technical documentation, it must infer:

👉🏾 What is context
👉🏾 What is instruction
👉🏾 What information is authoritative
👉🏾 What constraints matter
👉🏾 What format the user wants
👉🏾 Which information should be ignored

That’s a tremendous amount of interpretation (where things begin going sideways).

Tech writers understand this already because humans behave exactly the same way when our docs lack structure. 🤠

Read more