What Makes Documentation AI-Ready: Quality Writing

In my previous post, I explored how document structure principles that have served human readers for decades serve AI tools just as well. That post focused on structure and metadata, skipping the actual words within that structure.

I asked Claude what writing patterns make content easy or difficult to process. The principles it listed match the guidelines in the technical communication textbook I used teaching undergraduates. The fundamentals endure, whether you’re writing for human readers or AI tools.

Text patterns that help processing

These patterns reduce ambiguity and make relationships between ideas explicit. They help both AI tools and human readers follow your logic and find the information they need.

Claude identified these helpful writing patterns, which align with established technical communication principles:

Clear topic sentences

First sentence of paragraphs that state the main point
Reduces ambiguity about what follows

Explicit connectives

“However,” “Therefore,” “For example,” “In contrast”
Signal logical relationships between ideas

Defined terms on first use

“React (a JavaScript library)” vs just “React”
Especially important for acronyms and jargon

Concrete nouns over pronouns

“The authentication token” vs “it”
Critical when text is excerpted or out of context

Consistent terminology

Using “user session” throughout vs switching between “session,” “user context,” “active connection”

Date/time specificity

“March 2024” vs “recently” or “soon”
Timestamps that aren’t relative to publish date

Attributions and sources

“According to the CDC” vs vague “studies show”
Named entities I can verify

Quantitative precision

“Increased by 23%” vs “significantly increased”

Applying these principles to your technical writing makes content easier to process for both human and AI readers.

When style guides conflict with processing clarity

As I reviewed the preceding list, I realized that my default style guide flags some of these helpful patterns as problems. For example, explicit connectives like “however” and “therefore” currently get marked as wordy because combining multiple concepts in a sentence complicates the sentence and raises the reading grade level. The style guide prefers tighter prose, which has historically been a property of good technical writing.

This creates tension: what helps AI processing can feel verbose to human editors. The solution isn’t to choose one audience over the other. Explicit connectives help readers who are skimming, using screen readers, or reading in a second language—the same readers who benefit from clear structure. The ‘wordiness’ objection often reflects a preference for expert readers who can infer connections, over diverse audiences who benefit from explicit signaling.

Consistent terminology presents a different challenge. I use term lists and grammar checkers to enforce consistent term use, but automated tools can’t verify that you’ve used the correct term from your list, just that you’ve used a term that exists in the list.

Using topic sentences that establish a paragraph’s content is advice that’s straight from technical communication textbooks, but I don’t have automated tools that can check for them. This remains a writing discipline issue but might be something more advanced review tools can check.

Text patterns that create processing challenges

These patterns force both AI tools and human readers to work harder to extract meaning. They consume more processing resources—whether computational tokens or human attention—with no guarantee the reader will reach the intended conclusion.

Claude provided this list of text patterns that complicate processing:

Pronoun chains

“It uses this to connect to them so they can process it”
Requires tracking multiple antecedents across sentences

Ambiguous referents

“This approach” “The solution” “These methods”
When multiple candidates exist in prior text

Marketing speak

“Revolutionary,” “game-changing,” “next-generation”
High word count, low information density

Implied context

“After the incident” (which incident?)
“Following the update” (which update? when?)

Temporal vagueness

“Recently,” “soon,” “in the coming months”
Especially bad on pages without publish dates

Nested subordinate clauses

Long sentences with multiple embedded clauses
Not impossible, just increases cognitive load

Industry shorthand without expansion

“K8s,” “i18n,” “a11y” on first reference
Domain-specific abbreviations assumed as common knowledge

Passive voice without agents

“The decision was made” (by whom?)
“Errors were found” (by what process?)

Context-dependent words

“Above,” “below,” “here,” “this page”
Assumes visual layout I don’t see

Idioms and colloquialisms

“It’s not rocket science”
“We’re not out of the woods yet”
Can be ambiguous when used literally vs figuratively

Coreference resolution across distances

Tracking what “it,” “this,” “these changes,” or “the new approach” refers to across paragraphs creates the most processing difficulty. The challenge grows exponentially when multiple similar entities appear in the same discussion.

Here’s why coreference matters. Consider this common documentation pattern:

We tested Framework A and Framework B.
It performed well in benchmarks.
The team recommended it for production.
This was implemented last month.

Which “it”? What is “this”? In isolation, impossible to determine with certainty.

Text linting tools catch many of these issues. Reading grade level tests flag ambiguous, complex, and wordy constructions. Passive voice detectors exist specifically to catch agent-less sentences and, of course, any competent editor flags these patterns for correction.

What about images?

Images are where human and AI similarities might seem to diverge. Images appear to create different requirements for human and AI readers. Claude explained:

I can’t extract images from web pages myself. When I fetch a URL, I get the HTML/text but not the rendered images.

I got similar responses from ChatGPT and Google’s Gemini AI tools. What AI tools need from images should look familiar.

Claude explained its limitations with images:

I only see images when:

You upload them directly to our conversation

They’re embedded as base64 in HTML (rare)

I’m using browser automation tools that can capture screenshots

So, on a typical webpage with <img src="diagram.png" alt="System architecture">, I only see the alt text, not the actual image.

For AI tools, images can help—especially technical diagrams and annotated screenshots—but they must be uploaded separately to the AI tool for interpretation. Text in the web page remains more reliable. Alt text provides the primary interface to images. Good alt text combined with detailed captions often conveys more than the image alone. These are the same accessibility requirements that make documentation accessible to readers with visual impairments.

Images cost more to create than text. This analysis might help you weigh their value: critical for human readers who can see them and benefit from visual learning, less critical for visually impaired readers and AI processing that relies on textual description. However, adding the accessibility information that benefits human readers with visual impairments, also helps AI tools process the information. Another win-win for both human and AI audiences.

Bringing structure and writing together

Part 1 established that AI tools benefit from the same structural principles humans use: clear hierarchy, semantic markup, purposeful organization. This post shows they also need the same writing principles: clarity, specificity, explicit connections.

Combined, these principles create documentation that serves both audiences. Apply the structure from Part 1 with these writing patterns, and you’ll create documentation that’s accessible to humans and processable by AI tools.

The fundamentals persist. Technical writing principles from decades ago still apply to the newest technology. Each new tool gives us another opportunity to confirm why these principles matter.