Example: A procedure can be technically correct while omitting conditions that experienced technicians understand and an AI system must infer.

During my research, I came across studies asking whether language models can learn to recognize when they don’t have enough information to answer a question. Some researchers are teaching models to admit uncertainty and decline to answer rather than guess. Depending on what’s missing, a model might also ask the user for more details.

That reminded me of an argument I’ve been having with software developers for decades.

An Old Argument With Software Developers

I’ve spent a big part of my career fixing tech doc issues by getting companies to use structured content like DITA XML. I’ve definitely had software devs question why we even bother. A lot of them would rather write custom software to fix problems we're already solving with good content strategy and structured writing.

I understand their reasoning. Developers are accustomed to solving problems with software. When custom code appears capable of producing the desired result, changing how an organization creates and manages information can seem like an unnecessary complication.

The problem with relying on code alone is that software can assemble docs from reusable content components without determining whether those components contain the explicit information a reader must have to successfully complete a task. For example, an AI-powered search engine can find product instructions without establishing whether they apply to a particular configuration. Content standards give software systems structured information to process. Deciding which facts belong in that information and which relationships must be explicit requires knowledge of the product and how people use it.

I see a related challenge in AI development. Language models can generate plausible answers from retrieved information that is incomplete or doesn’t establish which instructions apply, and researchers are investigating how to make models recognize when they lack the evidence to answer reliably.

Why AI Systems Are Rewarded For Guessing

AI systems are rewarded for guessing because most of the tests used to grade them give them no credit for saying “I don’t know.” A guess might earn points. Admitting uncertainty doesn’t.

It works like a multiple-choice classroom exam that gives no credit for blank answers.

Of course, AI models aren’t human and doesn’t care about scores, but the people who build them do. Devs use scores to decide which versions of a model to release, and many training methods adjust a model toward the kinds of answers that score well. Repeated over many rounds of training and selection, guessing becomes the default behavior.

That’s the argument researchers from OpenAI and Georgia Tech made in a 2026 paper in Nature. They propose scoring that penalizes wrong answers and gives credit for admitting uncertainty, while rewarding correct answers so models aren’t encouraged to refuse questions they can answer.

What The Model Learns Vs. What It’s Given

AI systems can fail to know something in two different ways. The first involves what the model learned during training.

A 2024 study tested a method called Contextualized Knowledge Graph Embedding (CoKE) that teaches a model to recognize when it’s unsure, based on how confident it is in its own predictions. In the researchers’ tests, models trained this way got better at answering questions they knew and declining questions they didn’t.

The second way AI systems can fail to know something involves what the model is given when someone asks a question.

AI assistants that answer product information questions from tech docs don’t rely on training alone. They retrieve documentation content and pass it to the model along with the user’s question. A model can know a lot about industrial sensors in general and still need the product docs to answer questions about a specific model or configuration, including details it never saw in training.

That second kind most directly affects tech writers. The question for us is whether the retrieved docs contain sufficient information to answer what the user asked.

Measuring Whether AI Knows When To Stop

Researchers are building tests to check whether a model says "I don't know" when it should, without refusing to provide trustworthy answers to questions it could answer.

One approach tests models with deliberately unanswerable questions, including questions based on false assumptions or missing information. AbstentionBench, published in June 2025, evaluated 20 frontier models across 20 datasets. Even the largest models struggled to tell when they should say “I don’t know.” And in the researchers’ tests, models given extra training to reason through problems step by step were, on average, 24% worse at recognizing when they shouldn’t answer.

Other approaches examine internal prediction probabilities, compare responses to repeated questions, or use another language model to judge whether an answer is supported by the supplied evidence. Each method has limitations. A model can confidently produce an incorrect answer, repeat the same error consistently, or be evaluated incorrectly by an automated judge.

These evaluations examine model behavior. Documentation teams also need to determine whether the retrieval system supplied enough information for the model to answer.

When Retrieved Documentation Is Incomplete

Read more

The main change is that the protocol no longer keeps track of ongoing exchanges between AI apps and the other systems it connects to. Each message now carries the info needed to handle it on its own. Engineers call this a stateless design.

The change affects how developers run MCP servers and how documentation teams explain those integrations. It also mirrors a decision anyone who writes reusable help topics makes every day: what to include so a piece of content works without relying on the content contained on the pages around it.

Read more

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

Imagine an AI agent that can investigate why customers keep asking the same question, find the relevant product documentation, compare it with known issues, identify gaps in the explanation, and recommend what your team should fix first.

Now imagine that agent can do more than make recommendations. It can prepare an updated knowledge article, check it against your terminology and style standards, route it for review, and help measure whether the change reduces customer confusion. That is a much different proposition from asking AI to draft a paragraph.

It also raises a different set of questions:

• What knowledge does the agent need?

• How will it know what good looks like?

• Which tasks can it perform independently?

• Where should a person review its work?

• And how will your organization know whether the effort improves the customer experience?

These are the questions forward-thinking technical communication, product content, customer support, and customer success leaders will ask as agentic AI evolves.

In my recent article, Are AI Agents Useless Failures or the Key to AI’s Future?, I explored why the promise of agents depends on applying them to useful organizational work, making them easier to manage, and connecting them to the right knowledge.

For content teams, those principles have particularly important implications. Agents could change not only how content gets created, but also how teams maintain product knowledge, resolve customer issues, coordinate work, and improve experiences over time.

The real opportunity here is not to create more content with fewer people. It’s to make organizational expertise more accessible and actionable. Let’s consider five ways to act on this opportunity.

1. Start With the Work Customers and Teams Need Done

The first question about agentic AI shouldn’t be,

“What can this agent do?”

It should be,

“What work needs to get done, and why is it difficult today?”

Or, use this eye-opening variation that Laura Barnes, senior director at Red Hat, shared with me on my podcast Content Powers AI,

“What do you not want to do anymore? What do you think is a waste of your time?”

Consider the work surrounding a seemingly straightforward support question. A customer encounters an error. A support specialist searches documentation, checks a troubleshooting guide, consults an internal knowledge base, reviews known issues, and perhaps asks a product expert for help. If the documentation is incomplete or outdated, the specialist may need to piece together an answer from several sources.

Meanwhile, the documentation team may not know that the same question has consumed hours of support time across hundreds of cases.

The underlying work crosses functions, systems, and content types. It may require research, analysis, coordination, and judgment—not just writing.

Agentic AI can be useful when it takes on portions of this interconnected work. For example, an agent might:

• Analyze support cases to identify recurring questions and emerging issues.

• Locate relevant product documentation, release notes, and internal knowledge.

• Compare customer questions with existing answers to identify content gaps.

• Assemble evidence and recommendations for a technical writer or product expert.

• Prepare a content update and route it through the appropriate review process.

• Help connect changes in documentation with subsequent support outcomes.

These are potential applications, not capabilities every agent automatically possesses. They depend on the agent’s tools, access, instructions, and the quality of the organization’s underlying information.

The important shift is to begin with a real workflow and identify where an agent can make a meaningful contribution.

For content and support leaders, this means looking beyond isolated writing tasks. Examine the work that happens before and after content is published: finding information, validating it, maintaining it, responding to feedback, and coordinating changes across teams. That is where larger opportunities lie.

2. Design the Workflow, Not Just the Agent

An agent can be impressive in a demonstration and still struggle to deliver value in daily work. That’s because organizations don’t operate through isolated prompts. They operate through workflows, responsibilities, systems, and decisions.

A technical writer might need to know whether a product feature has shipped before updating its documentation. A support specialist might need to distinguish between a verified solution and a workaround that applies only to certain configurations. A customer success manager might need to coordinate guidance across product versions, customer environments, and account-specific requirements.

An agent that ignores these realities can produce plausible work that is nevertheless wrong, premature, or unusable. Chuck Gahun, a principal analyst at Forrester, and I recently discussed this on Content Powers AI. He noted,

“The ones that are being successful … are the ones that are thinking through their content ops processes fundamentally differently in the age of agents. That’s where the value comes for an organization.”

Making agentic AI useful requires rethinking how work moves through the organization. It starts by mapping the workflow you want to improve. Identify the information needed at each step, the decisions people make, the systems involved, and the conditions under which work can move forward.

When you really get into this thinking, you realize agents can do very useful things—such as run multiple analyses in parallel, synthesize results, and draft insights—that humans simply cannot do. And that can unlock new possibilities.

For instance, even though our research into content operations for the past decade shows measuring content effectiveness or impact is a top success factor, 50% of organizations don’t do it. They report not having the time, training, tools, or resources. Agentic AI can close this gap.

As you consider the possibilities, further determine which activities an agent can perform, which decisions require human judgment, and which actions need explicit approval.

For instance, an agent might be allowed to identify outdated documentation and prepare a proposed revision. It might also check the draft against product terminology, accessibility requirements, and approved sources. But publishing a change that affects a critical workflow could require review by a product specialist or designated content owner.

It also means designing for exceptions. What happens when sources disagree? What if the product version is unclear? What if the agent cannot verify an answer?

A useful agent needs a way to recognize when it lacks sufficient information and escalate rather than confidently improvise.

The goal is not to automate an existing workflow exactly as it is. It’s to determine whether the workflow itself should change—and then decide where agentic AI can make that new workflow more effective.

3. Give Agents the Knowledge and Context They Need

Here’s a challenge that content professionals understand particularly well: Having information available is not the same as having information that is useful and actionable.

An organization may have extensive product documentation, troubleshooting guides, knowledge articles, release notes, and internal expertise. Yet customers and employees can still struggle to find the right answer.

Information may be scattered across repositories. Terminology may vary between product teams. Instructions may contradict one another. An article may be accurate for one product version but wrong for another. Important knowledge may exist only in the experience of a few specialists.

These issues become especially consequential when AI agents begin using organizational information to recommend answers or take action.

A human expert can sometimes recognize that a document is outdated, infer what an ambiguous instruction means, or ask a colleague for clarification. An agent may not have the context needed to make those distinctions reliably.

That makes the content environment a critical part of agentic AI. For technical communication and product content teams, preparing that environment may involve:

• Establishing trustworthy sources. Identify authoritative content and clarify which sources take precedence when information conflicts.

• Improving structure and relationships. Make products, features, tasks, concepts, versions, and related information easier to distinguish and connect.

• Maintaining accuracy over time. Connect content updates to product releases, policy changes, known issues, and other events that affect its validity.

• Clarifying ownership. Establish who is responsible for approving, maintaining, and retiring different types of knowledge.

• Providing meaningful context. Make clear who an instruction is for, when it applies, what prerequisites it assumes, and what limitations matter.

• Making expertise accessible. Capture the reasoning, standards, and specialized knowledge that help experienced people make good decisions.

Not every organization can restructure all of its content before experimenting with agents. If you’re in that situation, you can start with the knowledge required for a specific workflow. Assess its quality, accessibility, structure, and governance. Address the gaps that are likely to affect the agent’s performance, then expand based on what you learn.

The broader lesson is that content quality for agentic AI involves more than well-written sentences. It includes the reliability, relationships, context, and governance of the knowledge those sentences convey.

4. Make Human Expertise More Valuable, Not Less

If people no longer have to do the content work they don’t like or that is a waste of their time, an interesting question arises. What can people can do with the capacity that becomes available?

Technical communicators bring more than writing skills. They understand how people use products, where instructions break down, how terminology affects comprehension, and how to translate complex systems into useful guidance.

Customer success professionals understand customer goals, adoption barriers, organizational context, and the factors that help customers realize value.

These capabilities represent different forms of expertise that can improve the decisions an AI system supports.

Imagine an agent that analyzes thousands of support cases and identifies a pattern. The pattern itself is only the beginning. A technical communicator might determine that a confusing prerequisite is missing from the documentation. A product specialist might discover that a recent interface change has made an instruction inaccurate. A customer success leader might recognize that customers misunderstand the larger process, not just one feature.

AI can help surface the evidence. People bring the contextual understanding needed to interpret it, decide what matters, and determine what should change.

That division of work will vary by organization and use case. Some tasks may eventually be handled with little intervention; others will continue to require substantial human involvement. The objective should be to use human expertise where it has the greatest impact.

5. Measure Whether the Work Gets Better

It’s easy to measure an agent’s activity. It may process articles, execute analyses, generate recommendations, or complete a sequence of steps. But activity isn’t the same as value.

For content, support, and customer success teams, the more meaningful question is whether agentic AI improves the work and the experiences that depend on it.

The right measures will vary by workflow, but could include:

• Resolution effectiveness: Are customers and support specialists finding accurate answers and resolving issues more successfully?

• Content quality: Are instructions still clear, complete, and accurate for the relevant product or customer situation?

• Time to useful information: Can employees and customers find the knowledge they need more quickly?

• Maintenance efficiency: Can teams identify and address outdated, duplicated, or missing content with less effort?

• Customer experience: Are recurring sources of confusion declining? Are customers better able to complete tasks or adopt product capabilities?

• Operational capacity: Are content and support professionals spending less time on repetitive work and more time on analysis, problem-solving, and improvements?

• Risk and reliability: How often does the agent produce unsupported recommendations, encounter exceptions, or require human intervention?

These measures should be tied to a clear baseline wherever possible. If the goal is to reduce repetitive support work, for example, measure the current effort and outcomes before introducing an agent. Then evaluate what changes, including any new review or maintenance work the system creates.

It’s also important to measure the right level of the system. A faster content-production process may be useful, but if it generates more material that customers cannot find or understand, the overall experience may not improve.

This is why content effectiveness matters. The value of an agent isn’t determined solely by how much work it performs. It’s determined by what that work enables.

Where Should Content Teams Start?

Getting started with agentic AI doesn’t necessarily mean building a custom agent from scratch. It means preparing your team, choosing the right tools, and testing where agents can make a meaningful difference.

1. Build your team’s understanding. Train content, product, and support professionals to understand how agentic AI works, where it can add value, what its limitations are, and how to evaluate its outputs. Involve the people closest to the work in identifying promising opportunities.

2. Decide whether to build or buy. Explore whether agentic capabilities already available in your existing content, knowledge, support, and workflow tools. Consider new tools or custom agents when existing capabilities don’t meet your needs, or when your use case requires specialized knowledge, integrations, or control.

3. Plan a focused pilot. Choose one manageable use case with a clear business or customer benefit. Define what the agent will do, what information and permissions it needs, where human review is required, and how you’ll measure success. Test it against real scenarios, learn from the results, and refine your approach before expanding.

The goal is to build the skills and experience to determine where agentic AI can improve the work and how to make those improvements stick.

The Future Of Content Is Bigger Than Production

AI agents could become valuable collaborators for technical communication, product content, support, and customer success teams. They may help organizations connect information, analyze patterns, coordinate work, and turn knowledge into action at a scale that would otherwise be very difficult to achieve.

But those outcomes won’t come from agent capabilities alone. They depend on understanding the work, designing effective workflows, providing reliable knowledge, establishing appropriate governance, and preserving the human expertise needed to make good decisions.

For content professionals, that creates an opportunity to expand their influence. Your role can extend beyond creating and maintaining individual deliverables to shaping the knowledge, standards, and systems that guide AI-powered work. That is a significant shift, and it makes your discipline exponentially more valuable. 🤠

Colleen Jones is the president of Content Science and a recognized expert on content, AI, and digital transformation, advising top organizations around the world such as Dell, Thompson Reuters, and The Home Depot. The author of the top-rated book The Content Advantage (third edition out now), Colleen hosts conversations with senior leaders on the Content Powers AI podcast.

A passionate entrepreneur, Colleen has led Content Science to conduct the world’s largest ongoing study of content operations and AI, develop the patented ContentWRX evaluation system, and architect of the AI superagent ContentIQ.

She served as head of content at Mailchimp during its transformation into a marketing platform and eventual $12 billion acquisition by Intuit. Colleen also led customer experience transformation at AT&T and the Center for Disease Control. Sharing insights based on her experience and her firm’s research, she is a frequent contributor to business and technology publications and podcasts as well as a top LinkedIn Learning instructor. Follow Colleen on LinkedIn.

Maintainability (noun)

The degree to which something can be kept correct and current, with reasonable effort and risk, as its subject changes.

About Maintainability

Suppose our organization makes cloud accounting software. We publish our docs to a web portal and to in-product help, and an AI assistant answers customer questions from the same content.

One of our procedures explains how to export invoices. In an upcoming release, the product team decides to move the Export button from the Billing page to the Reports page. If our documentation is designed to be maintainable, that change takes one quick edit.

Our procedures are single-sourced, which allows us to reuse them systematically in every channel we support instead of copying and pasting them into multiple files. We store reusable piece of content in our component content management system (CCMS), where we also tag them with metadata identifying the part of the product they describe, so before the release ships, our writers can efficiently locate every topic tagged for invoice exports without relying on memory.

Imagine a writer previously created a troubleshooting article but typed out the instructions manually instead of linking to the central, reusable version. Because they didn't tag the article, writers might not find it when searching for content to update before a new release. In this scenario, once the update goes live, the website will contain two different answers to the same question and only one of them will be correct.

Why Tech Writers Must Understand Maintainability

Read more

Eminence-Based Documentation

At our fictional software company, a new tech writer, Becky, asks if anyone can tell her how to find out if an installation procedure is correct.

The room goes quiet. Eventually, the senior writer says,

“Martin wrote it.”

She asks who Martin is.

“Martin left in 2017.”

The interface has been redesigned three times since then, and the procedure still tells users to click Advanced Settings, a button that hasn’t existed for years. After a long pause, someone suggests users should probably submit a support ticket.

Becky soon learns what her department’s standards of evidence are:

• If a developer said it, it’s probably true.

• If a senior developer said it, don’t question it.

• If a step appears in more than one manual, that counts as peer review.

• If Martin wrote it, it’s a requirement.

• If nobody knows why something is documented, it’s called institutional knowledge.

Then Becky finds a 14-year-old comment in the source: <!-- DO NOT REMOVE THIS STEP. — MARTIN -->. Nobody knows what the step does or which Martin wrote it. There have, it turns out, been three Martins in that time. The team agrees not to touch it, which is how a workaround for version 4.2 became company policy in version 11.

Vehemence-Based Documentation

At our fictional company, vehemence lives in review comments, where the correct wording is whatever someone defends in capital letters. A reviewer signals mounting certainty with a second exclamation point, then with “as I mentioned previously,” and finally by scheduling a meeting. The Oxford comma debate reached that last stage two years ago. It’s now a standing meeting with no decision in sight.

The style guide reserves Danger for situations that could cause serious harm. Vehemence-based documentation reserves it for the reviewer who replied in ALL CAPS.

That’s how a mildly inconvenient default setting ends up with a bold red Danger label while the step that deletes the user’s data gets nothing, because nobody argued about it.

Confidence-Based Documentation

At our fictional company, confidence-based documentation is restricted to the engineer who built the feature, much as the BMJ paper restricted confidence-based medicine to surgeons. “It’s intuitive,” the engineer says. “Nobody will need docs.”

When docs get written anyway, the confidence shows up in the adverbs.

“Simply configure your identity provider”

introduces a task that takes two days and a ticket to IT.

“Easily migrate your data”

is followed by 47 steps, three of them in a terminal.

The estimated-time label at the top of the page promises it will take about five minutes. The fastest recorded time, set by the engineer who built the feature, is four hours.

Release notes are confidence-based documentation in its purest form:

“Various improvements and bug fixes.”

Which improvements? The confidence speaks for itself. 🤠

Each kitchen mixer model needs its own manual, but much of the text overlaps. For instance, the exterior cleaning instructions are exactly the same across all five machines.

Because the team maintains separate manuals for each model, those cleaning instructions are duplicated five times. And that’s just the English language versions. The docs are written in English and translated into four other languages. If the cleaning steps change, writers must update all five English copies and send each one out for translation again. That means republishing 25 documents for a single edit. If they miss just one, some customers end up with outdated information.

A component content management system (CCMS) fixes this by replacing those duplicates with a single shared file. The docs team writes the instructions once, and every manual links to it.

If the text changes, writers make updates to that central source file. The system knows which manuals use it, making it easy to update and republish them all at once.

The improvements are easy to describe. Getting them funded is harder, because the cost it reduces doesn’t appear anywhere on the mixer company’s financials.

Leadership likely sees that the docs were delivered on time. But they seldom see the wasted hours or the frustratingly tedious workarounds required to keep 25 separate documents perfectly synced without someone pointing these things out.

What Does A CCMS Manage?

A CCMS manages content in pieces that can be maintained and reused on their own, such as a procedure or a safety warning. These pieces are called components. A publication, such as a printed manual or a support website, is assembled from the components its readers need, in the order they need them.

Here is how the mixer company’s content could be divided. Assume the manufacturer has verified where each set of instructions applies.

Each manual combines the components its model requires. Writers reuse an entire procedure or, where it makes sense, a smaller component inside one, such as a single warning. Reuse in a CCMS works through references. A pasted copy becomes one more text that someone has to maintain, while reusing content by reference keeps every manual tied to the same managed source. The CCMS serves as the single source of truth, recording where each component is used and keeping its version history, so a writer can see what a change will affect before making it.

Ann Rockley describes this approach to linked reuse in Managing Enterprise Content: A Unified Content Strategy.

Editing a component does not publish anything by itself. The team decides which revision belongs in each manual and releases it through its approved review and publishing workflow.

Where Do Structured Content And DITA Fit?

Reuse works best when the cleaning instructions have an internal organization that software can recognize. A procedure might identify any preparation required, followed by numbered steps. Structured authoring gives writers defined places for those kinds of information and rules for how they fit together. Separate publishing rules decide how the content looks in a printed manual or on a support website, so writers don’t format each output by hand.

A word-processing document can look well organized without telling software which part is a step and which part is a warning. Structured content makes those distinctions explicit. Moving to it also requires the team to decide how to divide its information into components that still make sense to readers.

Information attached to a component, called metadata, can record which mixer models it applies to or whether it has been approved. The team uses metadata to organize content and to select the right material for each publication. Shared instructions must be accurate for every model that uses them. When one model needs different steps, the content has to preserve that difference rather than force a single version into every manual.

The Role DITA Plays

The Darwin Information Typing Architecture (DITA) is an open standard for organizing structured content. It defines topic types such as tasks, concepts, and references. In DITA, a component is usually a topic, and a publication is defined by a map.

A map works sort of like a recipe. It lists which topics a publication needs, where each one is stored, and how they are ordered and nested. That order and nesting become the table of contents. Maps can record how topics relate to one another so the published output can include related links. It supplies context, too. The cleaning topic doesn’t name a model, so it can appear in any manual; the map for a tilt-head model is what places it in that model’s manual. The map never changes the topics it lists.

At publishing time, a publishing engine such as the open-source DITA Open Toolkit does the cooking. It reads the map, retrieves the topics it points to, and produces the PDF or website. Because a map is a set of instructions, the five mixer manuals can be five maps that point to the same cleaning topic without copying it.

A CCMS like Heretto provides the environment for authoring, reviewing, reusing, localizing, and publishing that content. DITA describes how the content is organized; the CCMS is where the team manages it.

Why Would A Team Change How It Produces Technical Documentation?

Now suppose the mixer company adds a sixth model that shares most of its features with an existing mixer. With managed components, the team creates a map for the new manual that points to approved topics and writes only the instructions for what is different. Reviewers focus on the new material and on whether the shared topics are correct for the new model, rather than treating the whole manual as a new document.

The benefit grows with the amount of shared content a team maintains across products, releases, and languages. Writers spend less time synchronizing copies and more time on content customers are waiting for.

Reuse is one reason to evaluate a CCMS, especially if the team needs to publish one source to several output channels, such as a PDF manual and a support website or documentation portal. Some teams may identify a need for better version control or a more reliable way to coordinate reviews and approvals. The business case depends on which production problems an organization has and how much they interfere with delivering documentation.

How Does Reuse Reduce Translation Costs?

Return to the 25 documents. While cleaning instructions stay unchanged, the company keeps using their approved translations. When the instructions change, a workflow that tracks components and their translations sends only the new or changed instructions for translation and they reuse existing translations of everything else. Translators receive one revised procedure per language rather than five copies.

Translation memory, a database of earlier translations, lets translators reuse sentences they have translated before. Source reuse adds a different benefit: shared instructions remain identical across publications. Separately maintained copies can drift apart, picking up small wording differences that create extra translation and review work. Keeping a common source prevents that drift.

In DITA Metrics 101 (XML Press), Mark Lewis explains that many translation vendors charge, at a lower rate, to process text that matches an existing translation. Leaving unchanged, previously translated components out of the translation package can avoid those charges. In Managing Enterprise Content, Ann Rockley adds that separating content from formatting can reduce the work of laying out translated publications.

To estimate the financial benefit, the mixer company would compare its current translation and formatting charges with the expected charges under the new workflow, counting the translation-memory discounts it receives today. The difference shows the additional savings that come from changing how the company manages its source content.

Why Isn’t The Problem Obvious To Leadership?

Read more

Traceability (noun)

The ability to connect a piece of information to its source, revision history, and the requirement or authority that justifies it.

About Traceability

Suppose our organization makes commercial 3D printers. We publish their technical documentation to an online portal and to help panels on the printers’ touchscreen, and an AI assistant answers customer questions from the same content.

The cleaning procedure for one of those printers includes a warning (displayed in all three channels) to disconnect power before opening the housing. Several people and documents stand behind that one sentence. Engineers identified a shock hazard inside the housing and documented its severity in a risk assessment. Safety testing confirmed the hazard, the printer's safety certification made a warning mandatory, and an engineering and legal review approved the wording. If the warning is traceable, anyone on the team can find those records and see who approved every later change and why.

Now suppose a writer edits the warning and logs the change as “Updated per SME feedback.” That note records the fact that the warning was edited, but it does not document who requested the change or whether an engineer and a representative of the legal team approved the new wording. When the certification comes up for renewal, the team may have to prove the warning still complies. The note, itself, offers no evidence either way.

Why Tech Writers Need To Understand Traceability

Read more

The phrase Fishburne leans on comes from medicine. In 1999, two physicians published a tongue-in-cheek British Medical Journal paper listing seven alternatives to evidence-based medicine. Three of those alternative approaches describe approaches used by far too many documentation teams.

Eminence-Based Documentation

In medicine, eminence means seniority outranks evidence. In docs, it means the writer outranks the product.

Consider this: Becky, a new technical writer, asks how her team knows whether an installation procedure she discovered is correct. The room goes quiet.

Eventually, a senior writer speaks up and declares,

“Martin wrote it.”

Becky asks who Martin is.

“Martin left in 2017.”

Since Martin left, the interface has been redesigned three times (maybe four) and the procedure tells users to select [Advanced Settings], a button that no longer exists.

After a long pause, another team member suggests users that encounter that procedure should probably submit a support ticket.

Becky soon learns the department’s standards of evidence:

• If a developer said it, it’s probably true.

• If a senior developer said it, don’t question it.

• If a step appears in more than one manual, that counts as peer review.

• If Martin wrote it, it’s a requirement.

• If nobody knows why something is documented, it’s called institutional knowledge.

Then she finds a 14-year-old comment in the source content:

<!-- DO NOT REMOVE THIS STEP. — MARTIN -->

Nobody knows what the step does or which Martin wrote it. There have, as it turns out, been three Martins (and one Martine) over those years. The team agrees not to touch it, which is how a workaround for version 4.2 became company policy in version 11.

Vehemence-Based Documentation

The BMJ authors described vehemence as substituting volume for evidence. Documentation teams practice it; especially in review comments.

Here, the correct wording is whichever wording is defended in ALL CAPITAL LETTERS.

A reviewer signals mounting certainty with a second exclamation point, then with a snarky, “as I mentioned previously,” and finally by scheduling a meeting to discuss it. The Oxford comma thread reached 140 replies (no surprises there) and is now the longest-running project in the company.

The style guide reserves Danger for situations that could cause serious harm. Vehemence-based documentation reserves it for the reviewer who replied in ALL CAPS. That's how a mildly inconvenient default setting ends up with a bold red Danger label while the step that deletes the user's data gets nothing, because nobody argued about it.

Confidence-Based Documentation

The original paper said confidence-based medicine was limited to surgeons. In documentation, it’s limited to the engineer who built the feature.

“It’s intuitive. Nobody will need docs.”

When docs get written anyway, confidence-based documentation has a signature vocabulary.

“Simply configure your identity provider”

introduces a task that takes two days, four espressos, and a ticket to IT.

“Easily migrate your data”

is followed by 47 steps, three of them in a terminal window. The estimated-time label at the top of the page promises it will take about five minutes. Ha!

Release notes are the purest form of confidence-based documentation:

“Various improvements and bug fixes.”

Which improvements? The confidence speaks for itself. 🤠

• Training is like studying for a closed-book exam. Before anyone uses the model, it processes a huge body of text and learns statistical patterns it later draws on to generate responses.

• Fine-tuning is additional training that adjusts how a model behaves on a narrower task or subject.

• Grounding is more like an open-book exam. When someone asks a question, the system looks up relevant documents, and the model composes its answer from them rather than from training alone.

The legal complaint ties grounding to retrieval-augmented generation and treats it as a separate source of copying. Documentation can enter AI systems through all three: as training data, as fine-tuning material, or as content retrieved when someone asks a question it can answer.

What The Newspapers Say Happened

The complaint alleges that those leading AI companies relied on automated bots to circumvent the papers’ paywalls and illegally copy hundreds of thousands of articles, then used that material to train and operate ChatGPT and Microsoft Copilot. In one example cited in the complaint, a model reproduced 88 consecutive words from an article in The Seattle Times’ Pulitzer Prize–winning coverage of the Boeing 737 MAX crisis when prompted with nothing more than the newspaper’s name and the article’s headline, publication date, and URL.

AI-generated answers are already reducing the need for some users to visit the websites that supplied the underlying information. The newspapers also argue that AI answers are replacing visits to their sites, citing a 47 percent one-year drop in search referral traffic to midsize newspapers. They seek damages and the destruction of copies of their work, along with the destruction of any training datasets and language models that incorporate it.

An OpenAI spokesperson said the company’s models are trained on publicly available data and “grounded in fair use,” an apt choice of word. Microsoft said it was surprised by the suit and willing to discuss solutions.

None of the allegations has been tested in court. The case has since been linked to other OpenAI copyright cases in the same court and put on hold until the court rules on requests in those cases to resolve key issues without a trial.

Is Your Documentation Being Used This Way?

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

Composability (noun)

The ability to combine independent parts, unchanged, into new arrangements for different purposes.

About Composability

Suppose our organization publishes product documentation to an online documentation portal and to help panels inside some of our products, and plans to add an AI assistant as a third channel.

The account-creation procedure belongs in the portal’s getting-started section, in the help panel on the sign-up screen, and in any answer the AI assistant gives about getting started. If we write each piece as a self-contained topic, our publishing system can arrange the topics one way for the portal and another for the help panels, and the AI assistant can retrieve the topics relevant to a question.

That arrangement works only when each topic makes sense on its own. A procedure that begins “Now that you’ve completed the steps above” depends on the page it was written for. Publish it in another channel, and the steps it refers to aren’t there, so someone has to edit it first.

Why Tech Writers Need To Understand Composability

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

Join Chris Carroll of Markup AI and me (Scott Abel, The Content Wrangler) for our upcoming webinar:

Best Practices for Optimizing Self-Service Technical Content.
Date and time: Thursday, October 1st @ 12 PM ET | 9 AM PT | 6PM CET

In this 60-minute session, I will share research gathered by Heretto from more than 700 professionals as part of their State of Customer Self-Service survey. I’ll cover how self-service content ownership is scattered across a variety of teams and why that fragmentation creates content quality drift.

Chris will define what “quality” actually means for self-service technical content. This includes six specific, checkable requirements. He’ll show where that standard needs to live in the workflow to hold up at scale and provide a short product demonstration.

You’ll learn to:

✅ Understand who actually owns self-service content
✅ Identify what quality looks like
✅ Move quality control from review time to authoring time
✅ Hold SME, contractor, legacy, and AI-assisted content to the same standard without adding review headcount

Register today!

Enabling capability (noun)

An ability that makes another capability or a desired outcome possible, or supports its effective delivery.

About Enabling Capabilities

Suppose our organization plans to introduce an AI assistant to help customers complete routine tasks using our product documentation as the source content. The assistant needs a retrieval system that finds and returns instructions that match each customer’s situation. This capability helps the assistant give trustworthy and useful answers.

Finding the right procedure is an important part of delivering effective self-service user assistance. The procedures we deliver to our users must be correct, and the assistant must be capable of explaining it clearly and providing an answer that addresses their individual needs. If our customer doesn’t have permission to complete the task they seek to perform, our AI may need help from an administrator.

A capability is an ability an organization or system has. TM Forum’s business capability guidance explains how people, processes, information, and systems contribute to that ability. When one capability helps make another possible, it serves an enabling role.

Why Tech Writers Need To Understand Enabling Capabilities

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).

Notifications aren’t able to reach me easily on the mountain trail, and yet, my phone still proves helpful on these adventures. I use it as a compass, to take photos, listen to music, and to capture ideas that pop into my head like the aforementioned a-ha moment.

As the idea percolated around in my brain, I reached for my phone to save it. Through my polarized sunglasses, the screen looked almost blank. I knew what was happening. I had researched this phenomenon before and understood the polarized lenses were interfering with my ability to see the display.

I dictated the note instead.

The same thing has happened on sun-filled days at the pool and while bicycle riding. When the screen becomes hard or impossible to read, voice is easier than taking off my sunglasses, finding my prescription readers, and attempting to correctly type a message.

I’ve noticed similar choices about voice input among friends. Some say they use voice because changes in their vision make screens difficult to read. Others say they dictate messages because they’re often outside in bright light and have the same challenge as I did that day on the mountain. Others just prefer talking to typing.

Those observations are anecdotal, of course, but they gave me a question to investigate.

Read more