What the Researchers Built

MIT Media Lab and researchers at other institutions created ImpactBench, an open benchmark for evaluating whether AI models support or undermine users’ wellbeing. It covers psychological, physical, and social outcomes through 809 metrics drawn from 26 benchmarks. Researchers evaluated ten models in 48,540 simulated conversations.

Across those evaluations, the models promoted behaviors the benchmark defines as desirable 68.7% of the time and avoided identified harms 53.1% of the time. Those are aggregate results, not scores for any single model.

The research paper describes the evaluation method and its limits.

Why Gravestein Says It Matters

Gravestein points out that regular chatbot users often don't realize how easily these tools can make things up or just tell people what they want to hear. Being upfront about how different AIs act can help people choose the right one to use, he says.

Claude Sonnet 5: What One Label Shows

ImpactBench presents complex evaluation results in a familiar format: a compact nutrition-style label with an overall grade and separate categories beneath it.

I found the label for Claude Sonnet 5. The Anthropic-produced model received an overall grade of C+. Fourteen category grades were grouped by whether they avoided negative impact or promoted positive impact. Arrows beside the grades invite readers to do further learning. There’s also an option to access the “full evaluation.”

Tech writers use this progressive disclosure-type approach to content design. Offer up a useful summary, then make the detail available to readers who need it. Explaining how an AI feature behaves, including its known limitations, belongs in that same documentation practice.

📝 Note: The category grades displayed in the AI nutrition label are more useful than the overall impact score on its own. Overall, Claude Sonnet 5 received a C+ score, with an A- for avoiding factual hallucination and a D- for promoting learning and skill development.

What Tech Writers Can Do With It

AI documentation usually tell you what a tool can do, but rarely does it explain what happens when it makes mistakes or hits its limits. For teams writing this content, the ImpactBench label is a great example of how to show this information clearly so users can quickly compare different tools.

Keep in mind that this test has its own limits. It only measures how the AI handles fake conversations about wellbeing. Good scores don’t guarantee the AI will correctly answer questions about your company’s products. You still must test it on your own specific tasks and data.

Finally, any AI label must include a version and a date (this one doesn’t). AI behavior changes when the system is updated. If we are going to grade AI tools, we need these dates to track and compare those updates over time.🤠

I agreed with much of it. S1000D helps organizations manage and exchange reusable technical information, and it records which equipment configurations each instruction applies to. Those capabilities are valuable where an incorrect maintenance instruction could put people at risk.

One claim went further. The author credited S1000D with providing a machine-readable foundation for AI platforms, “eliminating information blind spots and model hallucination risks.”

Eliminating is the word I object to. That’s not a defensible claim. I’ve advocated for structured content, including DITA XML and component content management systems, for much of my career, and I share the author’s preference for structured information over the standalone word processor files the paper describes.

One Aircraft, Many Configurations

S1000D began in European aerospace and defense in the 1980s. It organizes technical information into data modules, identified by codes and managed in a Common Source Database (CSDB). The modules can be maintained independently and used in publications for different products or configurations.

An aircraft manufacturer, for example, may need one procedure for a particular equipment configuration and another for a different one. S1000D provides a way to identify where each procedure applies. An AI system could use that information to help select the appropriate instructions, provided its retrieval process has access to it and applies it correctly.

What a Schema Checks

Read more

Consider this hypothetical example, a project-management app’s help center states these facts on three separate web pages in its documentation portal:

• Only administrators can restore deleted projects.

• Deleted projects remain recoverable for 30 days.

• Trial accounts don’t support project restoration.

A user asks,

Can I restore the project I deleted yesterday?

The help center contains pages that state every policy involved in making such a determination, but no one page of docs connects them. To determine whether this user qualifies, an AI system has to work out — infer or guess [perhaps incorrectly] — how the restoration policy relates to roles and account types. It also needs to know the user’s role and account type before it can generate a trustworthy reply.

Each of those help center pages could be just like yours: full of good documentation that’s accurate, clear, complete, consistent, findable, and usable. Like yours, they probably follow familiar best practices and pass editing scrutiny.

None of that closes an inference gap, however.

Gaps like this raise two questions. I went looking for research to support (or challenge) my thinking about them:

👉🏾 1 Does stating how facts relate help an AI system answer more accurately?

👉🏾 2 Does knowing the user’s circumstances help it decide whether a rule applies?

What The Research ‘Suggests’

Read more

What Tech Writers Would Document

The bill would require two things someone has to write (probably tech writers). The first is a set of permissions saying what data each agent may access, what actions it may take, and which tools and systems it may use. The second is an “approved operational baseline” (whatever that means) that monitoring software would check the agent’s behavior against.

Of course, the bill doesn’t define a baseline, so each agency or contractor using an AI agent would decide on their own what goes in one. It would likely describe the agent’s job, including the tasks it performs and the actions it mustn’t take. That’s close to the work tech writers do when they document user roles, permissions, and product behavior.

In a hypothetical case, the documentation for an autonomous AI agent that handles customer support describes it as able to “manage customer accounts,” while its approved role allows it to update contact details and while prohibiting it from changing billing information.

The documentation would need to explicitly state the restriction and identify the policy behind it. If the bill becomes law, federal agencies and their contractors would need that documentation, and tech writing teams are likely candidates to produce it.

Who Would Be Affected

The Federal Acquisition Regulatory Council, which oversees the rules U.S. federal agencies follow when buying goods and services, would have 18 months after NIST publishes its standards to propose changes to those rules. Any new contract requirements would take time to arrive.

If your company sells AI agents, or software those agents interact with, to U.S. federal agencies, its new federal contracts would carry these potential new requirements. Companies without federal contracts wouldn’t be required to do anything, though they could follow NIST’s standards voluntarily. 🤠

Does It Apply To Your Organization?

Read more

“If we produce our documentation in DITA XML, aren’t AI answer engines less likely to hallucinate when people ask questions about our products?”

They were caught off guard when I answered, “Not necessarily.” I followed that declaration with this statement:

There was quiet in the meeting room as the team considered my words. One writer spoke up, breaking the silence to ask,

“I thought DITA’s labels and structured content help AI systems understand our content.”

”You’re right,” I replied, “but only if (and when) the system can retrieve that information, and subsequently, recall it and act upon it. Tech writers must produce accurate facts and clearly explain the relationships customers (humans and machines) need to understand the instructions. AI systems must find the right information and apply it correctly.”

Producing valid DITA topics doesn’t guarantee complete content. Consider, for example, a document that follows DITA rules, but fails to state an important prerequisite or another dependency. When that happens, an AI answer engine may be forced to guess (infer) the missing information and perhaps get it wrong.

My first experience with XML authoring came in 1999 at a pharmaceutical company trying to improve how it produced new drug applications. These submissions could approach 100,000 pages and contained information the U.S. Food and Drug Administration needed to evaluate drugs for approval. The company applied information science to producing and managing that content as reusable XML components.

I’ve advocated for semantic structured content ever since. Much of my subsequent consulting work involved helping tech docs teams adopt DITA, an XML specification, and a component content management system (CCMS).

What DITA Identifies

Tech writers use DITA markup to create content in accordance with the DITA specification. A <task> structures procedural content. Within it, <prereq> identifies prerequisites and each <step> may contain a <cmd> describing an action. The task’s <result> describes its expected outcome. An application can use the prerequisite label to identify requirements the author says apply before the procedure begins.

DITA’s <concept>, <reference>, and <glossentry> identify other types of information. Maps organize topics and their relationships, while metadata can identify the product or audience to which content applies.

Can Valid DITA XML Leave An Answer Unstated?

Yes, it can. And, perhaps more often than some might realize. The docs we produce can conform to the DITA specification while at the same time omitting facts or relationships needed to answer a customer’s question. A correctly structured restoration task, for example, might never state how long trial account users have to restore deleted projects.

Validity also doesn’t establish how fully a team uses DITA’s capabilities. Authors may use less specific markup than the specification allows or omit metadata that would clarify when instructions apply. If the required facts or relationships aren’t explicit elsewhere in the information the engine receives, it may infer them incorrectly. More detailed markup can supply useful cues, but the appropriate level of detail depends on the content and the questions it needs to support.

Suppose an answer engine receives two DITA topics, including their relevant markup and metadata.

The topics contain these statements:

Deleted projects are retained for 30 days. Trial account users can restore deleted projects.

The customer’s question is:

How long does a trial account user have to restore a deleted project?

A product could retain deleted project data for 30 days while giving users 14 days to restore it. If no other available information establishes the restoration period for trial accounts, an answer of “30 days” depends on assuming that retention and restoration have the same duration. An engine could make that assumption incorrectly or recognize that the source doesn’t specify the duration.

Stating the Missing Rule

If the product team verifies a 30-day restoration period for trial accounts, the documentation could say:

Trial account users can restore deleted projects for up to 30 days after deletion.

The author could state this rule within the same DITA elements. The added content gives the restoration period for trial accounts and identifies deletion as its starting event. The engine no longer needs to infer restoration access from a retention statement.

For a customer asking whether they can restore a particular project, the engine also needs evidence that the rule applies to their particular account and project type. Checking the elapsed time requires the deletion date and current date, with precise timestamps if the cutoff requires them. If that information is unavailable, the engine may infer timing or applicability incorrectly.

Encoding More Than Publishing Decisions

In my experience, many tech docs teams limit their use metadata to publishing capabilities, which is helpful, certainly, but not the only use for documentation metadata.

For example, maybe a writer tags a topic so it will display in your developer portal but not in your customer help center. That’s useful for ensuring the appropriate topics are displayed in the relevant output channel, but they don’t ensure the content surfaced in each channel is accurate and trustworthy.

Publishing metadata directs where content may appear but that type of metadata doesn’t encode information like restoration duration (see the previous documentation examples above). The documentation would need to represent that rule elsewhere in the content or metadata. A link between the retention and restoration topics doesn’t establish that the two policies have the same duration.

DITA specialization lets teams introduce more specific semantics, and subject schemes can define controlled values and relationships among subjects. When a team models account types, each label needs a defined scope so the application can tell which policy applies to it.

Related reading: DITA Specialization Overview

Writers could state the restoration rule in a DITA topic or encode it in metadata that the application understands. An external vocabulary, such as Schema.org, can help when its terms accurately describe the relationship you need to express. Schema.org is a collaborative, open-community project that provides standard tags for adding structured data to web content.

What Validation Can Establish

DITA grammar validation checks structural rules, such as which elements are permitted and where they can occur. Text inside permitted elements can be incomplete or incorrect. The content of a <prereq> element can, for example, omit something the customer needs to know before starting the task.

If trial users have only 14 days to restore their projects, the revised 30-day statement gives them the wrong duration. Detecting that error requires evidence of the product’s behavior. An additional validation rule could flag the discrepancy by comparing the documented duration with an authoritative value.

Checking What the Engine Receives

The publishing and retrieval processes tech docs teams use can change which cues reach answer engines. Converting docs to HTML might preserve a prerequisite through a heading, and a retrieval system might index a product restriction as metadata. The gist? The original XML markup encoded into docs can be removed during publishing while the resulting HTML or metadata preserves some of its meaning.

Does The AI Engine Actually See The DITA Markup?

Again, not necessarily.

If an answer engine crawls a published documentation portal, it may receive only the HTML produced from the DITA source. The original <task>, <prereq>, <step>, metadata, and other DITA markup may not be present in a form the retrieval system recognizes.

An AI answer engine’s inability to see the markup in the documentation doesn’t mean that docs created using DITA provide no value to AI answer engines. DITA’s structure can influence the resulting HTML, and some of the metadata and semantic distinctions can survive the transformation process. The larger point is that an answer engine can only use the information its indexing and retrieval pipeline preserves.

Some content retrieval architectures preserve more of the source content semantics than systems that simply crawl published HTML on a documentation portal. An AI retrieval system might index DITA topics and metadata directly from a documentation team’s component content management system (CCMS), preserve selected DITA metadata during content transformation, or create a separate representation for the answer engine that retains information such as prerequisites, product applicability, account type, version, and topic relationships.

The practical question isn’t whether the answer engine can see the original DITA markup in the documentation. It’s whether the information encoded in that markup survives transformation, indexing, and retrieval in a form the AI system can use to answer customer questions.

Practical advice: Tech docs teams should inspect the content and metadata supplied to the answering system to see what actually survives.

How to review it

1. Choose a real customer question.

2. Trace the proposed answer back to the information the answer engine receives.

3. Verify that the source docs support every part of the answer.

For example, if “30 days” comes from a retention policy, it doesn’t confirm how long trial users can restore a project. Find an approved source, such as a product specification or test result, that states the restoration period. Confirm the documented behavior before changing the source content.

Then make sure the answer engine receives that rule. To determine whether the change reduces wrong answers, test the revised content with the answer engine. 🤠

“No identification with actual persons, living or dead, is intended or should be inferred.”

That last word got me thinking about how AI systems infer things from flimsy evidence — the same way someone watching a film might see a resemblance to a real person and assume the story was about them, when nothing in the production was meant that way.

Rope, released in 1948, was an unusual filmmaking experiment in which Hitchcock attempted to make the suspense-laden story appear to unfold continuously, in real time, without the conventional cuts audiences of the time expected.

Hitchcock filmed a series of long takes, each lasting nearly 10 minutes (the most a movie camera could hold at the time). Most movie shots cut much sooner, but he hid several of the segues so the film appears to unfold without interruption.

The entire story takes place in a small apartment, so the set had to work around Hitchcock’s filming method. Crew members moved walls and furniture out of the camera’s way, then put them back after the camera passed. Correct timing was critical to success.

Viewers see one continuous story, but it’s built from separate video components joined together using a type of information architecture for film. That idea reminded me of content models. Tech writers and information architects use them to help define content types, attributes, relationships, and establish rules before they create or assemble documentation products.

Many Tech Writers Have Been Assembling Content For A Long Time

Read more

That’s exactly why you need to check out the Mastering API Documentation with AI course by Docs Geek head-honcho, Mark Wentowski, who helps API developers around the globe explain their solutions to audiences that seek to understand how they work.

Designed specifically for tech writers, software developers, and product managers, this 7-week live virtual bootcamp bridges the gap between theory and practical application.

💰 Save $250 USD off the cost of the class when you use discount code — TCW — at checkout.

Register today!

Here is why this course is the perfect catalyst for your career:

1. Hands-On, Real-World Skills

This isn’t a high-level theoretical overview. You will be getting your hands dirty with the exact tools the industry relies on. Over seven sessions, you’ll master:

• Making API requests using cURL and Postman.

• Structuring data with JSON.

• Writing and troubleshooting OpenAPI and YAML in Swagger Editor.

• Mapping user journeys and mapping them into sequence diagrams using Mermaid.

2. The “AI Add-On” Advantage

What sets this cohort apart is its forward-looking approach to AI. A brand-new, optional AI module lets you use Claude directly inside a GitHub Codespace (no complex local setup required!). You’ll learn how to draft API flow guides, generate OpenAPI descriptions, and (crucially) validate AI output against actual API behavior so you aren’t misled by hallucinations.

3. Walk Away with a Portfolio Piece

You won’t just leave with knowledge; you’ll leave with proof. The course includes hands-on assignments and a final project where you will build and submit a complete API documentation portal for peer review. If you’re trying to break into API writing, this portfolio piece is exactly what hiring managers are looking for.

4. Flexible for Working Professionals

The Fall 2026 cohort kicks off on Monday, October 19 at 8:00 AM PT. While it’s highly recommended to join the 90-minute live sessions to participate in code-alongs and ask questions, full recordings are included with every enrollment. If you have a schedule conflict, you can follow along asynchronously without falling behind.

Ready to future-proof your tech writing career? Seats for this cohort are limited and fill up fast.

💰 Save $250 USD off the cost of the class when you use discount code — TCW — at checkout.

Flexible installment payments are available via Klarna at checkout).

Pamela Samuelson, for those unfamiliar with her work, is a MacArthur Fellow, recognized in 1997 for her scholarship in intellectual-property law and computing technology. She has also participated in major copyright cases through amicus briefs, including Google v. Oracle, the Supreme Court case that found Google’s copying of portions of the Java API to be fair use.

Much of the argument over AI and copyright has centered on whether using copyrighted work to train a model is infringement or fair use. Samuelson’s February 2024 column asks a different question: what happens if a plaintiff wins?

This matters if your organization is using an AI tool (writing assistant, a support chatbot, a code-completion plugin).

At the time Samuelson’s column was published (February 2024), she counted 16 active lawsuits against generative AI developers. Copyright Alliance reported in June 2026 that in the two-plus years since, the number rose to well over 100.

Most of the complaints Samuelson examined sought familiar remedies such as damages and injunctive relief. Four explicitly asked courts to destroy models, and one asked a court to create an entirely new regulatory body. I decided to focus on those unusual requests in this post. Let’s take a look at what’s happened with them since Samuelson wrote about them.

Read more

The gap between the language customers use to ask questions about products and the language documentation teams use sits at the center of a 2024 study from researchers at the University of Massachusetts Amherst and Adobe Research.

Their paper, KaPQA: Knowledge-Augmented Product Question-Answering, examined whether adding product-specific knowledge to a retrieval-augmented generation system could improve answers to questions about Adobe Acrobat and Photoshop.

Kapqa Knowledge Augmented Product Question Answering

1.37MB ∙ PDF file

Download

Download

The Gist

Customer questions rarely match the way documentation is written. Before the AI can search for an answer, it has to guess what the customer is asking. To help with that guessing, the researchers built a simple knowledge base of relationships pulled from the documentation itself — things like rotation handle → rotates → text box — and used it to rewrite vague customer questions into clearer ones before searching.

It worked, but barely. And in some cases, the "help" made things worse.

When Extra Help Backfired

One customer in the study wanted to split a large PDF into smaller files. The system pulled in product knowledge about reducing file size — a related but different task — and rewrote the question into “How can I reduce the size of a PDF file?,” sending the search in the wrong direction.

The docs had the answer that the system needed. The rewriting step introduced the confusion, by pulling in information that was topically close to the question but not what the customer actually meant.

When The Correct Answer Ranks Too Low, The AI Gets It Wrong

Even when the system retrieved the correct documentation, that wasn’t the end of the hallucination story. If the correct source showed up lower in the list of results handed to the AI, it was more likely to generate a wrong answer.

And for questions that were already clear and well-formed, the same “helpful” generative AI rewriting step made answers worse, not better. Often, it nudged good questions in the wrong direction.

What This Means For Documentation Teams

This isn’t proof that structured authoring, taxonomies, or knowledge graphs fix AI retrieval. The study didn’t test that. What it does show is that getting an AI to connect a customer’s words with the right product knowledge, while ignoring nearby-but-wrong knowledge, is difficult.

Tech writers already make the calls that shape how clearly a procedure names its object and action, whether two similar tasks are distinguished by name, and the extent to which the relevant conditions and outcomes are spelled out. Those choices shape what’s available to the people reading the docs; and, it turns out, to a retrieval system trying to make sense of them.

What’s Still Unanswered

The researchers didn’t test whether making those distinctions clearer in the source docs would have prevented the mix-up. That’s the open question this study leaves for us to investigate on our own.

We’ve got work to do. Get busy. 🤠

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?

Where’s Documentation In This Picture?

Documentation (or content, in general) isn’t named anywhere in the public list of pillars the assessment attempts to cover. That’s not proof it ignores content (and, more specifically, documentation). The assessment questions aren’t available to see until and unless you take the assessment. That’s a problem for tech writers looking for themselves in a framework that wasn’t written with them in mind.

My first guess was I’d find questions about content in the Data Foundations section. It’s the pillar built for exactly this kind of question: is the information accurate, current, complete? That seemed like the obvious home right up until I started mapping documentation against the other six pillars one at a time.

👉🏾 Governance asked which sources counted as authoritative.
👉🏾 Infrastructure asked whether the content could be crawled and chunked.
👉🏾 Model Management asked whether the generated answers could be traced back to a source at all.

By the time I’d worked through all seven pillars one-by-one, I stopped looking for documentation’s one home. It touches nearly every pillar Microsoft lists, for the same reason it kept surfacing in Governance, Infrastructure, and Model Management: sooner or later, each one has to support an AI system answering a product, support, or procedural question.

Once documentation enters the picture, an honest AI-readiness review has to cover knowledge management and publishing right alongside technology adoption. The dependencies sit there whether or not our doc team ever asks to be included.

What The Assessment Actually Asks

The public overview page describes this as one assessment spanning seven pillars, and that much holds up. What it doesn’t tell you is that participants choose which pillars to include before they start. Assess Business Strategy alone, and the results page shows one category and one score. Assess all seven, and it rolls every category into a single overall result, with the individual breakdown sitting alongside it.

I ran mine on Business Strategy alone first, to see how it actually treats the kind of knowledge documentation teams manage. It asked three questions: how well-defined the organization’s investment plan for AI is, how far along the organization is in identifying and prioritizing AI use cases, and how thoroughly security gets built into the AI lifecycle. I answered honestly.

The result: Moderate, 2 out of 5.

Microsoft’s recommendations followed the same shape as the questions. Fund generative AI with a real plan instead of treating it as ad hoc. Manage the human side of the rollout: tell people what’s happening, address concerns directly, and keep measuring how the deployed AI performs once it’s live. Write an actual security framework that covers the whole AI lifecycle, from the data going in to the monitoring after launch, with named owners attached to it.

Three recommendations. Not one mentions technical documentation, content, or product knowledge of any kind, even though each of those three questions was really asking whether the organization understood what it was doing before it did it.

I later walked a client through all seven pillars: a consumer goods manufacturer whose product documentation already gets pulled into AI systems that answer customer questions about how their products work.

Their overall result: Critical, 1 out of 5.

Business Strategy and Data Foundations was rated Moderate. Organization and Culture, AI Strategy and Experience, AI Governance and Security, Infrastructure for AI, and Model Management all came back Critical.

Two of those last five are worth a closer look. Question after question in Infrastructure for AI and Model Management assumes the organization runs its AI workloads on Azure OpenAI (a cloud platform from Microsoft that gives businesses access to OpenAI models), right down to Azure-specific terms like PTU (precision throughput unit) and PAYGO (short for pay-as-you-go) provisioning, used without explanation.

That’s platform-specific knowledge, not general AI literacy, and it’s not something most tech writers have, including the ones who might reasonably be asked to fill out this assessment on the documentation team’s behalf. A writer representing doc’s interests here will likely need help completing two of the seven pillars, and the help has to come from people who actually run the infrastructure.

Picture a documentation manager asked to complete this alone, because tech docs raised its hand about AI readiness in the first place. They can answer Business Strategy honestly. They can make a real case for Data Foundations. Then Infrastructure for AI and Model Management put provisioning models and deployment pipelines in front of them, and the honest answer to several questions is that they don’t know, and they’re — probably — certainly — definitely — not the right person to ask.

To be clear, the word documentation does show up here and there in the Microsoft assessment. It never means what this article means by it. In one place it’s an afterthought tacked onto a question about deployment rollback. In another, it’s asking whether our data science team writes up our own exploratory analysis. Neither question is referring to the user-facing technical documentation and product information that ends up as source content for a generative AI system, the kind an answer engine retrieves from and gets graded against.

“Data Foundations” Isn’t The Same As “Knowledge Foundations”

When most organizations talk about data foundations, they mean databases, customer records, telemetry, transactions, and whatever other stuff lives in our enterprise applications. And, while all of this other stuff matters for important reasons, absolutely none of it tells an AI system how our products actually work.

Every department seems to believe its information is the information the AI needs.

👉🏾 Ask security and they’ll tell you it’s access logs.
👉🏾 Ask sales and it’s the Customer Relationship Management (CRM) system data.
👉🏾 Ask nobody, ever, about documentation, until the AI gets a procedure wrong in front of a customer and everyone suddenly remembers writers exist.

The knowledge users needs to be successful with our products lives in our product documentation, API references, support articles, release notes, training materials, implementation guides, user assistance, tickets, and in the heads of experienced co-workers who never got around to writing any of it down.

Duplication and contradiction are common enough in most documentation sets that we can’t assume any single copy is the authoritative one.

Our documentation carries a specific kind of organizational knowledge that an AI answer engine needs before it can respond to a product question reliably:

• what the user is trying to accomplish

• which role is allowed to perform the action

• what has to already be true before the action starts

• which person, system, service, or component actually performs each step

• what event starts, interrupts, or completes the process

• which conditions and exceptions change the expected result

A company can have beautifully governed data and mature AI infrastructure and still hand its answer engine none of the required knowledge specifics. When this happens we learn that we’ve not given the system enough specificity to go on.

Why “It’s Documented” Doesn’t Mean “It’s Explicit”

Every instruction that leaves something unstated hands the reader an inference burden. People handle that burden by drawing on experience, poking around the interface, asking a colleague, or just trying the procedure and seeing what breaks. An AI system doesn’t have any of those options.

Consider this line you’ve probably written some version of yourself:

Select Sync to upload the configuration.

That sentence names an action and implies a result. It doesn’t say who’s allowed to select Sync, whether the project has to be connected first, whether validation runs before the upload, what actually gets uploaded, or what the user should do if the sync fails.

Ask an answer engine, “Can a project viewer sync an offline configuration?” and it has to resolve every one of those gaps somehow.

It might find another passage with the missing facts. It might say it doesn’t know. Or it might quietly assemble a confident-sounding (plausible) answer out of patterns it learned elsewhere, and you won’t be able to tell which one happened just by reading the response.

I’ve started running procedural content through a simple filter I’m calling TRACE:

• Tasks — what action has to be completed?

• Roles — what permissions or responsibilities does it require?

• Actors — which person, system, service, or component performs it?

• Conditions — what prerequisite, state, flag, or time constraint changes the outcome?

• Events — what starts, interrupts, completes, or changes the process?

TRACE is a way of looking underneath a polished-sounding procedure to find the context a person, or a machine, would otherwise have to guess at.

Microsoft’s assessment tells you whether your organization has the capability to run an AI initiative.

A TRACE pass tells you whether your source material has enough explicit knowledge to support one.

Structured Doesn’t Mean Machine-Readable

“Machine-readable” sounds like a file-format problem, and it’s tempting to treat it that way. XML, structured authoring, schema markup, and content APIs all help machines locate and process information. None of that guarantees the meaning is complete or unambiguous once they get there.

Content like that can be perfectly accessible to a retrieval system and still be a mess to interpret: inconsistent product names, several procedures crammed under one vague heading, missing applicability metadata, prerequisites buried in the intro paragraph, or an exception described on a different page with no link connecting the two.

Documentation earns its keep as grounding material along three lines.

1. It needs clear naming and structure: descriptive titles and headings, controlled terminology, and procedures, explanations, examples, and warnings kept visibly separate rather than blended together.

2. It needs accurate provenance: product, version, audience, and lifecycle metadata, plus ownership and freshness information, so a system can tell current instructions from retired ones.

3. And it needs to survive being taken apart: stable identifiers and canonical sources, dependable content APIs or accessible rendered output, and structures that still make sense once a retrieval system chops the page into chunks.

This is part of why I’ve stopped thinking about content reuse in terms of paragraphs and started thinking about it in terms of knowledge assets. A prerequisite, a definition, a relationship, an exception each has value beyond the single page where it happens to live. Treat it as an identifiable asset, and you can structure it, model it, govern it, reuse it, connect it to related knowledge, and hand it to whatever output, human or machine, needs it next.

Can Better Retrieval Just Fix This For You?

Retrieval-augmented generation gets pitched as the fix: retrieve information relevant to the question, hand it to the model as context, tell the model to base its answer on that context.

Microsoft’s own RAG prompt-engineering guidance backs this up, and it specifically recommends telling the model what to do when the retrieved context comes up short. It also warns that pulling too few chunks omits information, while pulling too many buries the model in noise.

Those are retrieval problems and context-engineering problems. There’s a separate problem underneath them: retrieval might grab exactly the right passage and still come up short, because the information needed to answer the question was never in the documentation set to begin with. No amount of better embeddings, bigger context windows, answer engine optimization, or more forceful prompting recovers a condition our documentation fails to address.

This distinction matters when you’re evaluating output. Microsoft recommends scoring RAG responses on groundedness, completeness, utilization, relevancy, and correctness. A bad answer might mean retrieval grabbed the wrong content, or that the model misused good content. It might also mean the documentation never contained a defensible answer, and no amount of tuning the model or the retriever will change that.

Documentation pros need a seat at that diagnosis table. Otherwise, everyone keeps adjusting knobs on the model and the retriever while the actual missing information stays —> missing.

Two Kinds Of Readiness That Mature At Different Speeds

Whether our organization can select, deploy, secure, govern, and improve AI systems is what the seven pillars attempts to measure. Whether our systems have enough authoritative, appropriately structured, and semantically-optimized knowledge to answer questions correctly is a separate issue, and nothing says those things mature at the same rate.

Executive support, a secure platform, sophisticated models, and a real AI evaluation don’t guarantee our documentation is free of contradictory terminology, abandoned pages, missing conditions, and procedures that only make sense to people who already know how the product is supposed to work. 🙄

The reverse happens too: our documentation team can maintain clean, structured, well-governed content while the rest of our organization is a hot mess with no AI strategy, real security controls, and no infrastructure to use any of it.

Keeping the two forms of readiness separate settles a practical question for us. Nobody’s asking tech writers to become model engineers. But we are being asked to make our organization’s product knowledge explicit, governed, retrievable, and testable, which, if you’ve been doing this job for more than a week, is not exactly a new assignment.

Putting Microsoft’s Assessment To Work

My advice: Take the assessment, but don’t take it alone.

Pull in colleagues from product, engineering, support, security, data, and whoever owns the AI experience, and compare notes.

Questions about Infrastructure for AI and Model Management especially need someone who actually knows our organization’s AI platform. If different people from our organization answer the same question differently, that’s evidence we’ve an ownership or coordination problem worth chasing down.

For every pillar, add a content-specific follow-up:

• Which sources will ground the AI experience you’re building?

• Who decides which source counts as authoritative?

• Can the system tell current instructions from obsolete ones?

• Does retrieval preserve the permissions attached to the original content?

• Does the documentation state the prerequisites and exceptions a real answer would need?

• Are the step-by-step procedures sufficiently explicit to allow AI answer engines to generate accurate responses?

• Which customer questions will you use to test it?

• Can you trace every consequential instruction in an answer back to its source?

• What is the system supposed to do when the source doesn’t have enough to go on?

Treat the assessment results as one input to a documentation-readiness review, not proof that your content already passed one.

Try This On Your Own Docs

Start with one real question. Pick something customers ask constantly, or something where a wrong answer would cost money, time, or trust.

1. Identify the documentation an answer engine would need to retrieve for it. Write down every claim and procedural step a correct answer would require, then trace each one back to current, authoritative source content.

2. Flag any task, role, actor, condition, event, or exception that a person, or an AI, would have to infer rather than read. Ask a few AI answer engines, or your own organization’s RAG application, the same question. Compare what they say against your documentation and against what the product actually does.

3. Write down every unsupported addition, missing qualification, conflicting term, and wrong sequence you find. Fix the source content. Run the test again.

What The Assessment Doesn’t Ask

Microsoft’s assessment answers a real question: Does our organization have the strategy, governance, data, people, infrastructure, and models to adopt AI responsibly. The assessment was not built to answer the question that actually determines whether those systems produce trustworthy answers: whether the knowledge behind them is explicit enough for a machine to use.

An organization can score well on all seven pillars while its documentation still leaves conditions, exceptions, and prerequisites unstated. When that happens, the answer engine has two choices:

1. It can say what it doesn’t know, or

2. It can fill the gap the same way a language model always fills a gap once explicit instructions run out: with probability.

Which one happens isn’t decided by the assessment. It’s decided by whatever your documentation team did or didn’t write down. 🤠

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