What to Fix by Hand After an Agent Writes the Docs

A generated document is confidently wrong in a way a human draft rarely is. The prose is clean, the sections are there, the tone is even. It reads like a manual assembled by someone who has seen a manual but has never once used the machine. Somewhere inside it, a step refers to a button that does not exist, or a number is rounded into uselessness, or a safety line is so broad it protects no one. Fixing that document by hand is unglamorous work, and it is work that nobody is doing right now, which is why the class of defects keeps spreading.

The temptation after an agent produces a draft is to treat the output as finished and move on. That instinct fails because writing a document and knowing a thing are two different activities. The agent has learned hundreds of thousands of documents and learned almost nothing about the specific object, process, or device the document describes. A person who has actually changed a tire, installed the valve, or closed a support ticket holds a store of small, awkward, physical facts the model has never encountered. Those facts are the part that must be restored by hand.

Numbers That Round Into Harm

The most reliable defect is the vanished precision. A generated guide will say to tighten the fitting "hand tight" because that phrase appears constantly in similar documents. Hand tight is not a specification. It is a placeholder that means one thing for a plastic cap and something frightening for a steel bolt. The number that belongs there, a torque in foot-pounds or a clearance in thousandths, got smoothed away because the model lacked the specifics and filled the hole with a comfortable phrase from its training data.

Scan every quantity in the document against something real. A temperature range, a thread count, a mixing ratio, a maximum load. If the document writes "approximately" or "around" before a measurement that actually has a hard limit, restore the hard limit. The vagueness reads as caution and functions as a liability. A reader following a rounded number can damage equipment, and the document will have told them to do it.

Watch for numbers that are internally inconsistent. Generated text can state two different figures for the same quantity in two separate sections because each section was composed without memory of the other. A spec sheet that lists a maximum operating pressure of 60 psi in the overview and 75 psi in the procedure is a document that will be trusted and then contradicted. Cross-checking every repeated figure is boring, manual, and absolutely necessary.

The Steps That Skip a Hand Movement

Procedures written by agents tend to be logical and physically impossible. They list the correct sequence of results but omit the intermediate movements that make those results happen. A step will say "attach the hose to the pump" without mentioning that the collar must be pushed back first, or that the fitting is left-hand threaded, or that the connector seats with an audible click and a person must listen for it. The omission is invisible on the page and obvious to anyone holding the hose.

The repair for this is to perform the procedure mentally with the object in front of the person doing the repair. Every verb in the document is a place to stop and ask what the hand is actually doing. "Insert," "secure," "seat," "align": each one hides a motion. The document needs that motion named, because a novice reader has no way to supply it. An expert reader will supply it automatically and then be annoyed that the document made them do the work twice.

Ordering is the other soft spot. Agents frequently arrange steps by topic rather than by physical sequence, producing a document that reads well and cannot be followed. If step four requires the part that step six installs, the document is broken, and the break is easy to miss because each individual sentence is sound. Reading the steps aloud in order, without the summaries and the subheadings, exposes most of these inversions. The document should be walkable end to end with nothing skipped and nothing installed after it is needed.

Invented Names and Fake UI

Software documentation generated by an agent is especially prone to inventing interface elements. The prose describes a "Settings" panel, a "Configure" button, a "Save and Continue" dialog. Some of these exist. Some are plausible names for things that are actually called something else. A generated guide to a tool it has never opened will confidently route a user through menus that were removed two versions ago, and the user will conclude the tool is broken rather than the document.

Every named control, menu, field, and button in the draft needs to be checked against the actual product. This is the most tedious verification in the whole job and the one that saves the most support tickets. Where a control has a tooltip or a keyboard shortcut, add it by hand; the model rarely knows these and they are exactly what experienced users reach for. The same rule applies to product names, part numbers, and model designations. A digit transposed in a model number sends a reader to the wrong manual, and the wrong manual may be the last document they read before damaging the equipment.

Safety Language That Protects No One

Generated safety copy is a particular hazard because it sounds authoritative and commits to nothing. A warning to "use proper precautions" and "ensure a safe working environment" has the cadence of real safety language and none of the content. The actual warning names the hazard, the condition under which it appears, and the consequence of ignoring it. "Do not open the housing while the unit is connected to power; the capacitor retains a charge after shutdown" is a warning. "Exercise caution when servicing electrical components" is wallpaper.

Any safety instruction in a generated draft should be treated as a placeholder until a person with real knowledge of the equipment rewrites it. The rewrite needs to be specific to the device and specific to the failure. Where the document makes a health or injury claim, keep the language cautious and general, and let the specificity come from the mechanism rather than from invented statistics. A warning that describes the actual hazard does more work than one that cites a number nobody can verify.

Voice That Belongs to the Product

The tone of a generated draft is usually a mildly formal neutral, which is fine and forgettable. What it lacks is the vocabulary the actual audience uses. A document about a piece of field equipment, written by someone who has never been in the field, will call a part by its catalog name while every technician calls it something else. The generated text is not wrong, exactly. It is foreign, and foreign documentation reads as untrustworthy even when every fact is correct.

Restoring the vocabulary is a matter of editing terms, not rewriting sentences. Swap the formal name for the working name, or give both on first use. Insert the phrases that the audience actually uses in the troubleshooting section, because that is where the reader is most anxious and most likely to search the text for their own words. A document that uses the reader's language gets followed. A document that uses a purchasing department's language gets skimmed and abandoned.

The Examples That Never Arrive

Generated documentation is long on description and short on example. It will explain that the input accepts a value in a certain range without ever showing a valid value and an invalid one side by side. It will describe an error condition without showing the message the user will actually see. Examples are where a reader calibrates. Without them, the reader has to guess what correct looks like, and guessing is the failure mode the document was supposed to prevent.

Adding examples by hand is fast and disproportionately valuable. One worked input, one expected output, one common error and its fix. These are exactly the artifacts the model tends to omit because they require ground truth it does not have. Where the document contains a code sample, run it. Where it contains a configuration snippet, apply it to a clean environment. A single broken example will cost more reader trust than a page of awkward prose, because the reader who tries the example and fails will stop believing the rest of the page.

The Parts That Should Be Deleted

Hands-on repair also means subtraction. Agents pad. A generated document will contain a paragraph explaining why the procedure matters, a sentence restating what the previous sentence just said, a transitional phrase that exists to move between two sections that did not need to be adjacent. None of it is false. All of it costs the reader time and dilutes the parts that carry actual instruction.

The deletion pass is the one most often skipped, because adding feels like improving and cutting feels like losing work. A document that has been trimmed to its instructions reads faster, gets followed more closely, and fails less often. Cut the motivational paragraph at the top of the procedure. Cut the restatement. Cut the closing paragraph that summarizes what the reader just did. What remains is a document a person can use while holding tools, which is the only test that matters.

The measurable cost of skipping this work shows up months later, in a support queue full of questions the document should have answered, or in a returned unit that failed because a step was performed in the wrong order. The document looked finished. The agent wrote it in seconds, and the draft was clean enough that nobody gave it the hour of skeptical reading it needed. That hour, spent with the object in hand and the draft open beside it, is the difference between a document that exists and a document that works.