What Makes Documentation AI-Ready: Media

In previous posts, I’ve explored how structural principles, writing quality, and code example pedagogy that serve human readers also serve AI tools. Those posts focused on text-based content found in all technical documentation.

This post addresses media: images, videos, diagrams, and audio. These elements appear less frequently in API documentation than in other technical content, but they’re valuable for tutorials, demonstrations, system architecture explanations, and physical procedures.

The patterns that make media accessible to AI tools aren’t new requirements. They’re the same accessibility standards that have served vision-impaired readers, users who have difficulty hearing audio content, and people with cognitive disabilities for decades. Once again, the fundamentals endure.

What accessibility standards tell us about media

The Web Content Accessibility Guidelines (WCAG) have provided clear requirements for accessible media since the late 1990s. These requirements weren’t created for AI—they were created for people who can’t see images, can’t hear audio, or need alternative ways to process information. To address these cases, they recommend:

For images:

Provide text alternatives (alt text) that describe content and function
Include longer descriptions for complex images like diagrams
Don’t rely on color alone to convey information
Ensure text in images is also available as actual text

For video:

Provide synchronized captions for deaf and hard-of-hearing users
Provide audio descriptions for blind and vision-impaired users
Provide transcripts that include both dialogue and important visual information
Identify speakers in multi-person videos

For audio:

Provide text transcripts
Identify speakers
Note non-speech sounds that convey meaning

These requirements are the result of thirty years of refinement based on how people with disabilities use content.

How AI tools process images

I asked Claude how it processes images in documentation. The patterns it described align exactly with accessibility requirements.

February 17, 2026February 21, 2026

What Makes API Documentation AI-Ready: Code Examples

In previous posts, I explored how structural principles and writing quality standards that serve human readers also serve AI tools. Those posts focused on the prose found in all technical documentation. API documentation presents an additional challenge: teaching concepts through code examples.

I asked Claude what makes code examples easy for an AI tool to process. The patterns it identified align with established principles from instructional design and technical communication pedagogy. Once again, the fundamentals endure—whether you’re teaching human developers or enabling AI tools to extract meaning from documentation.

Code presentation patterns that help processing

Claude identified the following helpful patterns for presenting code in documentation.
I’ve added comments in italics to Claude’s conversation for additional context and clarification.

Syntax highlighting with language specified

```javascript
// Language tag makes intent clear
const result = await fetchData();
```

versus unmarked blocks requiring inference

Complete, runnable examples

Includes necessary imports and dependencies
Shows actual input and expected output
Avoids fragments with ellipses everywhere

I discuss the nuance of this later in the article.

Inline comments explaining non-obvious logic

```python
# Convert UTC to user's local timezone before display
local_time = utc_time.astimezone(user_tz)
```

Variable names that indicate type and purpose

userConfig vs data
isAuthenticated vs flag
errorMessage vs msg

February 16, 2026February 21, 2026

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”

February 15, 2026February 21, 2026

What Makes Documentation AI-Ready: Structure

It’s that time again when I refresh my API Documentation course for the next term. In the course description, I emphasize that I’m teaching foundation skills to write good API documentation, not the latest tools. Students need to use tools to produce documentation, so I teach how to learn new tools while teaching those foundation skills. They learn GitHub as the representative example—experiencing both a documentation tool and how foundation skills look when instantiated as actual documentation.

After adding AI tools to the course last year, each refresh has taken more time. AI technology advances faster than I can teach the course, creating real tension: should I keep focusing on fundamentals, or chase the latest AI capabilities?

A recent Write the Docs discussion gave me the answer I needed. The conversation started with an article promoting DITA as the solution to produce AI-readable documentation. It sparked debate about tools and approaches and revealed something more fundamental: AI tools don’t need anything new to read documentation. They need the same structural principles that information scientists and technical writers have relied on for decades.

The fundamentals aren’t outdated. They’re just being rediscovered by each new technology.

What the discussion revealed

An article titled Why AI Search Needs Intent (and Why DITA XML Makes It Possible) kicked off the Write the Docs discussion by promoting DITA (Darwin Information Typing Architecture) as the solution for making documentation AI-readable. The article’s premise is solid: users often can’t articulate what they need, and structured content helps guide them to answers.

Our discussion consensus: structure is definitely important, but we had less certainty about DITA as a requirement to provide that structure. DITA does enforce topic structure and information architecture, but it requires significant overhead in authoring tools, training, workflow changes. I’ve used DITA-like tagging at several organizations. It’s not trivial. Other approaches can achieve similar results: a Markdown-based system with consistent templates and frameworks like Diataxis, for example.

August 21, 2025February 21, 2026

Testing antagonistic AI review on my own writing

I’m terrible at spotting flaws in my own work. As I iterate through multiple drafts and careful editing, I still tend to lose myself in the details and focus more on the trees than the forest. It’s not uncommon for me to miss weak arguments, unclear explanations, and assumptions that need defending—until after I publish, of course.

While preparing my previous post about AI writing workflows, I decided to test something: asking Claude to actively look for problems with my draft from an antagonistic perspective. Not just gentle feedback, but the kind of opposition you’d face from readers with strong opposing viewpoints.

The results were more brutal than I’ve been used to from Claude, yet they were more useful, than I expected. Here’s what I learned by using adversarial review to stress-test arguments, and why this technique shows promise despite some significant limitations.

The experiment setup

Close to publishing, I gave Claude this prompt:

Review the most recent draft as an antagonistic reader who would like to find any and all problems with the article (whether constructive or just to be antagonistic). This reader might have a pro-AI agenda to push or an anti-AI (as in no AI can be good) agenda.

I was looking for the kind of opposition that finds every possible angle of attack—the readers who come to your work already convinced you’re wrong and looking for ammunition to prove it.

Claude responded by creating and applying three distinct antagonistic personas:

The ideological opponent (challenges core assumptions and claims bias)
The pedantic critic (nitpicks definitions and demands citations)
The bad faith reader (misrepresents positions for rhetorical advantage)

Then it proceeded to tear into my article from both pro-AI and anti-AI perspectives. I had asked for this, and the responses were deliciously brutal. They were antagonistic in exactly the way I’d requested, and to be honest, genuinely useful.

What different types of opposition reveal

Claude organized the feedback by its perspective on AI. What follows is a summary of the feedback. You can see all the feedback in the transcript of the chat.

August 19, 2025February 21, 2026

How to get honest answers from AI tools (hint: better questions)

Google Cloud recently published “Smarter Authoring, Better Code: How AI is Reshaping Google Cloud’s Developer Experience,” describing how they’re applying AI to documentation challenges that every technical writing team recognizes: keeping content accurate, current, and useful for developers working with constantly evolving services.

Because AI tools consistently claim to excel at content analysis and summarization, I put that claim to the test on this article. I’ve been working with these tools for about six months now and wanted to test what I’d learned. So, I fed the Google article to Claude and spent some time exploring what it could tell me about the content, the claims, and the gaps.

Spoiler alert: the questions I asked mattered more than the answers I got.

The thought leadership gap: Style over substance

The Google article describes two main AI applications in technical writing:

Integrating Gemini into writers’ authoring environments for productivity tasks like generating tables and applying style guides, and
An automated testing system that uses Gemini to read documentation steps and generate Playwright scripts for validation.

The article also describes a multi-agent system for code sample generation that uses Protobuf definitions as source of truth, with generator agents creating samples and evaluator agents scoring them against rubrics.

Claude initially provided a summary that was cleaner and better organized than my mental notes after reading the same article. However, when I pushed for evidence supporting the claims, Claude articulated what I’d been sensing: the article provides limited concrete evidence beyond “over 100 tests daily” and references to “tens of thousands of idiomatic samples.” There was no mention of metrics on accuracy improvements, time savings, before/after comparisons, or validation of claims about preventing “factual drift.” You can see the whole conversation in the chat transcript.

When I questioned Claude about why Google would publish such a detail-light article, Claude offered a perspective that troubled me:

For thought leadership aimed at developer relations leaders and engineering executives, too much evidence could backfire. Publishing specific metrics creates comparison benchmarks that competitors can target. On the other hand, a claim like, “Over 100 tests daily” suggests impressive scale without revealing whether those tests actually pass.

That bothered me. We’re talking about a business communication norm where impressive-sounding claims matter more than verifiable results. Claude put it bluntly: “There’s an ethical gap between presenting a technical approach and implying proven success.”

February 20, 2022February 21, 2026

Writing UI text—less is more, taken to the extreme

Less is more is a mantra frequently heard in technical writing. When applied to editing, this works out to be something like, “After writing, keep taking the words out until it stops making sense, then put the last word back in.”

While this approach applies to technical writing in general, it comes into sharp focus in user interface (UI) text where both time and space are in very short supply. The reader/user is often in a hurry and there’s no space to put any extra text.

The key to success with such approaches to minimalism is to know your audience. I’d like to share a couple of examples of knowing your audience and how this resulted in two different outcomes.

The examples

The first example is an interface from the piClinic research project I conducted from 2016-2019. In that project, I was trying to learn if limited-resource clinics in Honduras that used a paper-based records with no automation could successfully adopt a small-scale computerized record keeping system. This project was low budget in every dimension, but I’d researched the requirements thoroughly and felt like I understood the user well enough to design a system that would work for them. The field tests in 2019 confirmed that hypothesis.

The second example is from a recent update to the Amazon Web Services (AWS) Console interface that I worked on. In this project, I collaborated with a talented team of UX designers, program managers, and developers to update the interface and improve its usability. My role was primarily the text on the interface; however, the text, design, and implementation are all intertwined.

Compared to the piClinic, the AWS project had much more talent and support behind it. In retrospect, the budget certainly influenced the design and the implementation of each project, but the approach to crafting the words used (or not used) in each of the interfaces had a lot in common.

The text in both interfaces was designed to meet the target users where they are.

November 28, 2021February 21, 2026

I love it when things just work

Bob Watson piloting a light plane on a sunny day as it approaches the runway to land

_{The image is a still frame from a video I pulled out of my archive to edit and an example of things just working–I’m on the final approach to a silky touchdown at Orcas Island airport.}

In user experience parlance, they call that customer delight. I recently had some experiences as a customer that delighted me. It was amazing!

I hope that my readers get to experience similar delight when they read my docs. Let’s unpack these recent delights to see how they might help improve my writing.

The experiences

It really started with a recent disappointing purchase experience, but first some back story.

About 20 years ago, I used to edit videos, among other things. Back then, computers took a lot of tuning (i.e. money) to meet the processing demands of video editing and effects. After several software and hardware iterations, I finally had a system that had the industry standard software running on a computer that could keep up with the challenge of video editing.

With that, I could finally focus on the creative and productive side of editing without having to fuss with the computer all the time. It’s not that I minded fussing with the computer–after all, that’s what I had been doing all along to get to this state of functionality and reliability. Rather, I don’t like fussing with it when I have other things that I want to accomplish.

It was truly a delight to be able to focus on the creative and productive aspects of the job. Having reliable tools made it possible to achieve flow. If you’ve ever achieved that state, you know what I mean. If not, read Finding Flow: The Psychology Of Engagement With Everyday Life by Mihaly Csikszentmihalhi.

Fast forward to this past week.

I finally upgraded my very-consumer-y video editor (Pinnacle Studio) to edit some home videos. I’d used an earlier version a few years back and I recall it having a pretty low learning curve for what I wanted to do. But my version was getting stale, and they were having a sale, so…

I paid my money, got my download, and was ready for the delight to begin!

Not so fast. There would be no delight today.

March 5, 2019February 21, 2026

The documentation cliff

For the past couple of months, I’ve been refactoring the piClinic Console software to get it ready for this summer’s field tests. Along the way, I encountered something I’d seen before, but never really named, until recently.

The documentation cliff.

A documentation cliff is where you get used to a certain level of documentation quality and support as you embark on your customer journey to use a new API and then, somewhere along the way, you realize that level of support has disappeared. And, there you are, like Wile-E-Coyote, floating in air, looking back at the cliff and looking down at where you are about to fall in the next instant.

Just kidding. What really happens is that you realize that your earlier plans and schedule have just flown out the window and you need to refactor the remainder of your development plan. At the very least, it means you’re going to have some uncomfortable conversations with stakeholders. In the worst-case scenario, you might need to re-evaluate the product design (and then have some uncomfortable conversations).

Most recently, this happened to me while I was using Postman to build unit tests for the piClinic Console software. I don’t want this to sound like I don’t like Postman–quite, the contrary. I love it. But that just makes the fall from the cliff hurt that much more.

How I got to the cliff

In my case, the tool was easy to get started with, the examples and tutorials were great, the online information was helpful–all the things that made a very productive on-boarding experience. So, I on-boarded myself and integrated the product into my testing. In fact, I made it the centerpiece of my testing.

December 23, 2018February 21, 2026

Recent good, could-be-better, and ugly documentation experiences

During the “break” between semesters, I try to catch up on the tasks I’ve deferred during the past semester and get ahead of the tasks I know will come up during the coming semester. In the process, I’ve had these encounters with documentation that I’ve characterized into these categories:

GOOD: documentation doing what it should—making me(the customer) successful.
COULD-BE-BETTER: documentation that is well-intentioned, but needs a tweak or two.
UGLY: documentation that gives me nightmares.

Here goes.

Good documentation

These are the stories of documentation that made me successful. Being successful makes me happy. Good documentation should help make the reader successful.

Ford Motor Company. F-150 owner’s manual

The windshield wipers on my almost 3 year-old truck are the ones that it came with from the factory— almost 3 years ago. Well past their expiration (and effectiveness) date. But, while I’ve changed car engines and gear boxes before, I hate changing wipers. They always have some clever (and obscure) trick to getting the old ones off and the new ones off. I especially hate it when they go flying off the car in a rain storm. So, for all these reasons,I’ve procrastinated on changing them for far too long (as driving in recent wet weather has reminded me)—the replacements have actually been in my garage since…I actually can’t remember.