Writing for the Machine Reader: A Practical Style Guide for the RAG Era

My last piece traced the 20-year arc of content retrieval in technical writing — from the Table of Contents, to Ctrl+F, to search engines, to RAG and AI assistants. The response I heard most often was some version of: okay, but what does that actually change about how I write a sentence?

Fair question. I have a degree in philosophy so theory is easy. Rewriting a procedure so a retrieval model doesn’t mangle it is harder — and it’s a genuinely different skill from the ones we spent the last two decades building.

So this is the practical follow-up. Below, I’ve taken the same piece of content and written it three ways: as it would have appeared in a printed manual, as it would appear in DITA-style structured content for online help, and as it needs to look for AI and RAG retrieval today. Same information, three very different sets of assumptions about who — or what — is reading it, and how.

The example: Resetting a device to factory settings

Version 1: The book era

In a printed manual, this content lives inside a chapter, and it’s allowed to lean on everything that came before it.

Chapter 6: Maintenance and Troubleshooting

…As discussed in Section 6.2, if the unit continues to behave unpredictably after you’ve tried the steps above, you may need to restore it to its original state. To do this, locate the small recessed button on the underside of the unit mentioned earlier. Press and hold it using the tool provided in the box. Refer to Figure 6.4 for the button’s exact location. Hold for the duration specified in the table at the start of this chapter. Once complete, follow the setup process described in Chapter 2 again from the beginning.

Notice what’s doing the work here: the surrounding chapter. “The tool provided in the box,” “the table at the start of this chapter,” “as discussed in Section 6.2” — none of this is self-contained. It doesn’t need to be. The book assumes a reader who arrived via the Table of Contents, in order, with context accumulating as they go. Retrieval was the reader’s job — they navigated to this exact page — so the writer could economize on repetition and lean on structure instead.

Version 2: The DITA / structured-content era

Move online, and content has to survive being landed on directly — from a search engine, a “related articles” widget, or a support agent pasting a deep link into a chat. The chapter is gone. Each topic has to stand alone.

Reset your device to factory settings

Use this procedure if your device isn’t responding to standard troubleshooting steps.

What you’ll need: A paperclip or SIM-eject tool

Steps:

1. Locate the reset button on the underside of the device, next to the serial number.
2. Using a paperclip or SIM-eject tool, press and hold the button for 10 seconds.
3. Release the button when the status light flashes white.
4. The device restarts and enters setup mode.

Next step: Complete initial device setup

This is a huge improvement, and it’s the DNA of modern topic-based authoring (DITA, docs-as-code, most structured CMS platforms): the topic is self-contained, front-loaded with the goal, has a clear prerequisite, numbered steps, and a link forward instead of a vague callback. It’s built for a reader who searched “reset device to factory settings” and landed here with zero prior context. It’s also — not coincidentally — SEO-friendly: a scannable H1, a clear intent match, structured steps a search engine can even lift into a featured snippet.

But notice what it still assumes: a human is reading this, in order, top to bottom, seeing the whole topic at once. The link at the bottom assumes someone will click it. The heading assumes someone will read it before the steps, not after.

Version 3: The RAG / AI era

Now assume this content gets chunked — split into pieces of maybe 200–500 tokens each — embedded, and retrieved individually based on similarity to a user’s question. A model might retrieve only step 2, or only the “what you’ll need” line, without the heading, without the surrounding steps, without the link at the bottom. It has to make sense in isolation.

Agent-Friendly

How to factory reset [Product Name]: Locate the recessed reset button on the underside of [Product Name], next to the serial number. Using a paperclip or SIM-eject tool, press and hold the reset button for 10 seconds until the status light flashes white, then release. [Product Name] will restart and enter setup mode automatically. A factory reset erases all saved settings and paired devices; it does not require a paperclip if your unit shipped after 2025, which include a built-in reset switch instead.

Human-Friendly

Factory reset [Product Name]

Factory reset [Product Name] by locating the recessed reset button on the underside, next to the serial number, and pressing and holding it with a paperclip or SIM-eject tool for 10 seconds until the status light flashes white, then releasing it — [Product Name] will restart and enter setup mode automatically. A factory reset erases all saved settings and paired devices. Units shipped after 2025 have a built-in reset switch and don’t require a paperclip.

At a glance: (this portion is for humans to scan faster)

• Tool: paperclip or SIM-eject tool (not needed on units shipped after 2025)
• Hold time: 10 seconds, until the status light flashes white
• Result: device restarts into setup mode; all settings and paired devices are erased

Notice the bulleted summary doesn’t introduce any new information — it re-presents facts that already live, complete, in the paragraph above it. That’s the key discipline: the prose paragraph is the source of truth and has to survive being retrieved with nothing else. The bullets are a convenience layer for a human skimmer, not a second, thinner copy of the answer that could get out of sync with the first.

A few things changed, deliberately:

• The product name is repeated, not implied. “The device” or “the unit” is fine when a human is mid-page and knows what page they’re on. It’s ambiguous to a model that retrieved this chunk alongside three other products’ reset instructions.
• Every fact is in one sentence, not distributed across a numbered list a model might retrieve partially. If step 2 (press and hold) and step 3 (release condition) get chunked separately, an AI answering “how long do I hold the reset button” might only retrieve step 2 and miss the release condition entirely. Collapsing the critical facts into fewer, denser sentences reduces the chance a model synthesizes an incomplete answer from a partial retrieval.
• The caveat about newer units not needing a paperclip is stated explicitly and locally, not in a separate “Note” callout three paragraphs later that might not get retrieved in the same pass. If a model retrieves the main instruction without the caveat, it will confidently tell someone to hunt for a nonexistent recessed button.
• No forward-pointing links, no “as shown above,” no “see the next section.” There is no next section, as far as a retrieval system is concerned. Every chunk needs to be a complete, correct thought on its own.

Five practical shifts this demands

Pulling the pattern out of that example, here’s what changes concretely in how I write and structure content now:

1. Say the noun, don’t point to it. “It,” “this,” “the device,” “the above setting” — all fine for a human mid-page, all landmines for a model that retrieved this sentence without what came before. Repeat the specific noun even when it feels redundant to a human reader.

2. Put the caveat next to the fact, not after it. The old pattern was: main instruction, then a “Note:” box a few lines down with the exception. If retrieval only grabs the main instruction, the exception disappears. Caveats that materially change the answer belong in the same sentence or the same small chunk as the fact they modify.

3. Design around chunk boundaries, not just page boundaries. DITA-era thinking asked “does this topic stand alone?” RAG-era thinking asks “does this paragraph stand alone, and does this individual step stand alone?” Numbered steps are still good for human scanning, but consider whether the single most important fact from a multi-step procedure survives being retrieved as one isolated chunk.

4. Write the answer, then the context — not the other way round. This isn’t new (it’s the same “front-load the point” advice from the SEO era), but it matters more now. A model summarizing a chunk tends to weight earlier sentences more heavily. Bury the actual answer in sentence four and there’s a real chance it gets dropped from a generated summary entirely.

5. Treat terminology consistency as non-negotiable, not a nice-to-have. This has always been technical writing 101, but it’s existential now. If your docs alternate between “factory reset,” “hard reset,” and “restore to defaults” for the same action, you’re not just mildly confusing a human skimmer — you’re splitting your own content across different embedding clusters, making it less likely a retrieval system pulls all the relevant pieces together for a single question.

What doesn’t change

It’s worth saying plainly: none of this is a rejection of DITA, structured authoring, or single-sourcing. If anything, RAG rewards the disciplines that discipline already taught us — modularity, clear scoping, one topic doing one job. The shift isn’t “throw out topic-based authoring.” It’s “apply the same self-containment logic one level down, from the topic to the paragraph, and stop assuming any surrounding structure — headings, notes, links — will travel with the text you wrote.”

The book era optimized for a reader moving through a full structure in order. The DITA era optimized for a reader landing on one complete topic. The RAG era has to optimize for a reader — human or model — that might only ever see one sentence of what you wrote, with nothing around it to lean on.

Write like that sentence has to survive alone. Because increasingly, it does.