Your Documentation Has Two Audiences Now

In August 2024, MadCap Software published a piece called AI for Technical Writers. It is a good article and it holds up better than most of what was written that year. It listed seven places AI helps: drafting outlines and first sections, retrieving knowledge, translation and localization, sorting content into DITA topic types, quality assurance against a style guide, automating formatting and indexing, and analyzing requirements to scope a doc set. It closed with the reassurance the profession needed at the time, that AI cannot replace human expertise and judgment.

Every item on that list is still true. Two years on it is also the floor rather than the ceiling, and the reason is not that the tools got better at those seven things, although they did.

The reason is that one assumption underneath the whole list quietly stopped being true. Every item assumed the technical writer is the last step. Write it, review it, publish it, a human reads it. That was the shape of the work for forty years and it is the shape the seven use cases were fitted to.

It is no longer the shape. Your documentation now has a second audience, and that audience does not read the way people do.

When a business runs an AI system that answers questions, drafts replies, or takes action, that system does not know anything about the business by default. It knows what it can retrieve. In practice that means the documentation is chunked into passages, embedded as vectors, and pulled back a few passages at a time when something in a query looks semantically close.

That process is unforgiving in a specific way, and the way it fails is a writing problem rather than an engineering one.

If a procedure buries its actual answer in the sixth paragraph under a heading that describes the department rather than the task, retrieval returns the wrong chunk. Not a slightly worse chunk. The wrong one, confidently, with no signal that anything went wrong. If the same concept is called three different things in three documents because three different people wrote them, the retrieval splits across all three and the system answers from whichever fragment happened to score highest. If a topic runs four thousand words without a subheading, the chunk boundary lands mid-argument and the passage that comes back is a sentence fragment with no subject.

Read that list again and notice what it actually is. It is a list of the things technical communication has been teaching people to avoid since Robert Horn was writing about information mapping in the 1960s. Information typing. Minimalism. Controlled vocabulary. Consistent, task-oriented headings. Chunking, which the discipline has literally called chunking for decades.

Those practices were always defensible on human-factors grounds, and they were also, honestly, the first thing cut when a deadline came. The change is that they are now load-bearing. A badly structured doc set does not merely read poorly. It makes the AI system built on top of it wrong, in public, to a customer.

Here is how we would rewrite that 2024 list for the work as it exists now. Not seven tasks AI can help with, but five shifts in what the job is.

From drafting to specifying. The first draft is the cheapest thing in the process now, which inverts the value of the work. What is scarce is the specification: the precise statement of audience, scope, constraint, tone, and what must never be said. A writer who can produce that document is more valuable than one who can produce prose, because the specification is what makes the prose reproducible by anyone or anything.

From style guide to context document. A style guide told a human what to do and relied on the human to remember it. A context document is loaded into the system every time it runs. This is a genuinely new genre with genuinely new constraints, and it is being written badly almost everywhere right now, mostly by engineers, because nobody has told the technical communicators that it is theirs.

From publishing to grounding. Publishing used to be the end of the pipeline. Now the doc set is a live retrieval corpus, and the questions that matter are different: where does this chunk break, does this heading carry enough meaning to be found on its own, does this passage still make sense with the four paragraphs around it removed. That last one is the whole discipline of standalone topic writing, suddenly with a machine enforcing it.

From editing prose to verifying behavior. When the system acts rather than just describes, quality assurance changes target. The question is no longer only whether the sentence is correct. It is whether the thing the system did matches the thing the documentation said it would do. That is closer to test design than to copy editing, and it is a skill most programs do not yet teach.

From information architecture to capability architecture. Structuring a doc set and structuring the set of things an agent is allowed to do turn out to be nearly the same problem: naming, scoping, disambiguating, and defining the boundaries between overlapping things. Anyone who has untangled a taxonomy will recognise the work immediately.

We run an internal AI system called Brian that handles operations for our business and for client accounts. It is not a demo, and the writing problems in it are specific enough to be worth sharing, because they are the kind you only meet in production.

Its knowledge is authored, chunked and embedded, so everything in the section above is a daily concern rather than a theory. A fact written as a clear standalone statement under a task-shaped heading comes back when it is needed. The same fact written as an aside inside a long narrative does not, and there is no error message telling you so.

Corrections are written back as short rules, and those rules have a hard character budget. The reason is unglamorous and instructive: the block of rules assembled into each prompt is byte-limited, and rules are selected by an importance score. A long, carefully hedged rule is not more thorough. It is a rule that pushes a better one out of the window. We landed on roughly 140 characters. Writing a genuine behavioral correction in 140 characters is a real constraint-writing exercise, and it is the most technical-communication-shaped task in the whole system.

Some of our documentation is machine-generated on a daily schedule and refuses hand edits by design, because a hand edit would be silently overwritten on the next run. So a correction to a generated doc has to be written as its own document that explicitly supersedes the wrong one. Version control, single sourcing, and the question of what to do when the source of truth is a program rather than a person. These are old problems in an unfamiliar costume.

And a straightforwardly unsolved one, which we would rather state than paper over. We do not have a good way to measure whether a given document is well written for retrieval short of trying it and seeing what comes back. There is no readability score for this. It is a genuinely open problem, and it is the kind of thing a research program could take a real bite out of.

If you are in a technical communication program right now, you have probably been told some version of the reassurance in that 2024 article: AI is a tool, your judgment is safe. It is well meant and it undersells your position considerably.

The honest version is that the artifact you produce is changing and the underlying skill went up in value. Organisations are discovering, usually the expensive way, that their AI system is only as good as the written material behind it. They are staffing for that discovery. The roles have unattractive names right now, and they are all recognisably the same job: someone who can take messy institutional knowledge and render it structured, unambiguous, and retrievable.

The gap is not knowledge. Programs teach the theory well, and the theory turns out to have been right. The gap is that almost nobody graduating has seen a live system where the documentation is actually load-bearing, watched a retrieval go wrong because of a heading, or written to a byte budget. That is a hard thing for a program to provide, because it needs a production system to point at.

We have one of those systems, and we are glad to open it up.

What we can offer a program or a class, at no cost: a guest session walking through a running agentic system with the documentation layer visible, including the parts that fail. Real anonymised examples of retrieval going wrong and the writing fix that resolved it. A set of student project briefs drawn from open problems in our own knowledge base, including the measurement one above, which we genuinely do not have an answer to. And for students who want to go further, a place in the AI Mastermind program, which is the hands-on version.

We would ask for something back, and it is worth naming plainly rather than pretending this is charity. We want the critique. We are a small firm building this in the open, our documentation practice is better than most and nowhere near what a discipline that has been at this for sixty years would call rigorous, and a room full of people trained to find the ambiguity in a sentence is exactly the audience we want reading our context documents.

If you teach in this field and any of that is useful to your students, the workshops are open and free, and that is the easiest place to start.

The 2024 article closed by saying AI cannot replace human expertise and judgment. That is still right, and it is worth being precise about why, because the usual reasons are sentimental and the real one is not.

The systems we build are not aware of anything. They know what has been written down for them. When the record is thin, a well-built one asks and a badly-built one invents. Everything downstream of that, whether the answer is right, whether the action was appropriate, whether the customer was well served, traces back to whether somebody wrote the thing down clearly.

That was always the technical communicator's argument for why the work mattered. It used to be a hard argument to win, because bad documentation mostly produced a frustrated reader who muddled through anyway. Now it produces a confident, fluent, wrong answer at scale, and the argument makes itself.

One test we would offer for evaluating any of this, including us. Ask what the system actually did, then go and check. Not what it can do, not what it monitors. What did it send, to whom, on whose authority, and what happened next. A system that answers that in specifics is one you can manage. A system that answers in adjectives is one you are trusting on faith. That is a documentation question too, and it is the one we would most like students to be ruthless about.