Category: Best practices

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.

Continue reading “What Makes Documentation AI-Ready: Media”

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

Continue reading “What Makes API Documentation AI-Ready: Code Examples”

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”

Continue reading “What Makes Documentation AI-Ready: Quality Writing”

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.

Continue reading “What Makes Documentation AI-Ready: Structure”