Posts

Posted on

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.

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

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
Continue reading “What Makes API Documentation AI-Ready: Code Examples”
Posted on

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”
Continue reading “What Makes Documentation AI-Ready: Quality Writing”
Posted on

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.

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

Reflections on my first AI-enhanced API documentation course

Now that the last quarter has ended and the holidays are behind us, I finally have a chance to reflect on the API documentation course I taught last fall. Last summer, I integrated AI tools into the course that I’d taught for two years. What I discovered: when students can generate content faster with AI tools, your evaluation process needs to keep pace, or you won’t catch problems until students have already repeated them multiple times. I suspect this applies to any course where instructors encourage AI use without rethinking their feedback loops.

I encouraged students to use AI tools and they did. They were generating content faster than in previous course iterations. What I didn’t anticipate: they hadn’t completely installed the linting tools that were part of the authoring system. Their use of AI tools let them produce assignment after assignment without applying the linting tools that should have caught basic errors. In one module with three assignments, more than two-thirds of students submitted work with style violations, such as lines exceeding 100 characters, missing blank lines around headings. Their local linters should have flagged these immediately, but their linters weren’t installed or weren’t working correctly, and I didn’t discover this until after they’d submitted all three assignments with the same problems repeated.

In previous iterations of the course without AI tools, students generated content slowly enough that I’d evaluate early assignments and catch tool issues before they could compound. Adding AI tools to the mix changed the velocity assumptions. Because of the additional AI-related curriculum, I grouped these three writing assignments into a single module. By the time I evaluated that module and saw one error, it had already been repeated three times—per student.

Continue reading “Reflections on my first AI-enhanced API documentation course”
Posted on

I’m not an AI hater. Really!

After a particularly tiring vibe coding session with Claude, I shared some of the resulting grumpiness in a few posts to the Write the Docs slack. I’ll confess. I’m probably not AI’s (as the term is currently bandied about) biggest fan. But I’m not a hater. I’m just, well, disappointed with it. It’s just not living up to its purported potential (a.k.a. hype, these days).

I’d been writing code (i.e. prompting Claude to write code for me, a.k.a. vibe coding) and Claude’s code was getting buggier and buggier. I’ve seen that happen before after it’s written a lot of code. It acts like it’s tired, but I think it’s due to having too many things to keep track of in the conversation, so it loses its place (I’m not an AI psychologist…yet).

In any case, I was beginning to wonder if it would have been faster to just start typing my own code (it wouldn’t), but I wanted to see how it played out. Eventually, after Claude had gotten stuck, again, I was troubleshooting in parallel and suggested a fix. Lo and behold, Claude agreed (as always). With that experience still fresh in my head, I went to the Write the Docs slack to see how others were faring in their AI journeys.

Thinking of past bubbles

In one post, I compared current AI hype to the hype I recall when PCs (as in IBM PC) came out in the early 80s. They promised the moon and in microscopically fine print, mentioned that “some assembly was required.” Sometimes some C, as well. (If you know, you know.)

In the 80s, it’s not that PCs weren’t amazing pieces of technology that could fit on your desk and still have room for your phone and desk blotter. Remember, this was a time when computer hardware had to have its own air-conditioned office. It’s that they lacked the “killer app” (the application that solves a high-value problem for a large audience), until Lotus 1-2-3 & Multiplan, two of the first spreadsheet apps), came out and ran on the PC.

Those killer apps transformed the PC from a geeky novelty to an absolute necessity. They enabled regular people to see the value that these machines could provide. Fast-forward to today, that’s how AI seems to be positioned: A novel (to most non-AI researchers and developers) technology waiting for its “killer app.” Just like the PC could do anything, but nobody cared until it did something useful. It’s hard to tell what AI’s killer app will be until we see it. If I knew what it was, I wouldn’t be here writing another blog post; I’d be working on AI’s killer app!

Continue reading “I’m not an AI hater. Really!”
Posted on

AI reflects on my reflection

After publishing my last post, I asked Claude what it thought about it, using the “reflective blog post” prompt I’ve been developing. It appears that we have some more work to do, indeed.

Claude reviewed my post in terms of:

  • Authenticity
  • Professional stakes and relevance
  • Voice and intellectual honesty
  • Process documentation quality
  • Factual accuracy
  • Overall assessment

Basically, I got a report card from my mechanical English teacher. Let’s see how I fared…

Authenticity

Evaluates whether the uncertainty and professional challenges feel genuine rather than manufactured for content purposes.

Let’s see what my strengths in Authenticity are, according to Claude:

  • Genuine uncertainty: The author demonstrates real ambivalence about AI collaboration without rushing toward resolution (“I’m not ready to abandon my AI-overlord, er, I mean co-writer, just yet”)
  • Honest stakes: Clear professional and personal impact – less satisfaction, feeling like work, questioning writing identity
  • Specific observations: Concrete details about the back-and-forth editing process, watching drafts transform, losing sense of accomplishment
  • Temporal authenticity: Uses present-tense investigation language (“What I think this really means…”) and frames conclusions as provisional

OK. So far, so good. What does Claude think I need to work on?

  • Limited process transparency: Doesn’t show systematic methodology for investigating this challenge beyond informal reflection
  • Missing specifics: Could benefit from more concrete examples of the “soul removal” process or specific editing exchanges

Perhaps. However, I’m not convinced those are appropriate in a reflection paper. It could be that we have a difference of opinion on what a reflection paper should include. Or, perhaps, adding more of this information would make it stronger. In retrospect, I think I’m still figuring out those aspects of my writing, so I’m still not quite sure what to say about them.

I’ll give Claude credit for identifying some inner workings that I need to process.

Professional stakes and relevance

Examines how clearly the article demonstrates real workflow impact and broader applicability to others in the field.

Continue reading “AI reflects on my reflection”
Posted on

Reflections on co-writing with AI

(Full disclosure, unlike recent blog posts, this post was not reviewed or edited by an AI before it was published. What you see is what you get from the real, organic, me.)

After the past few articles, I thought I’d pause to reflect for a moment on what I thought about my recent co-writing with AI experiences.

Less soul

First up, it’s been a bit weird to watch my first drafts transform into the finished blog posts. It has seemed like work, for starters. Running my copy through an editor, revising, discussing revisions, more revising, and ultimately publishing (or not in a couple of cases). Sounds like a job to me, as compared to just me, myself, and I working through a few iterations before publishing.

As I review the interim versions, I see myself slipping away, then I re-insert myself, then the AI applies more style guide, and then I take that back, etc. What I think this really means is that I need to work on the guiding prompt to reduce some of this back-and-forth.

More organization

As it removes my soul, I think the resulting content is more organized and, perhaps, easier to read at the end of the process. Or rather it seems to have less of MY soul. Despite crafting an AI prompt to produce my “style.” Does this mean that my natural writing is disorganized?

Perhaps.

I prefer to think of myself being “differently organized.” I think my natural, blog-post writing has more of a “stream-of-consciousness” feel, although I try to keep it understandable–and I rarely publish a first draft. It seems like changing the organization to suit the audience removes the “authentically human” nature of the non-AI articles. Again, perhaps another clue to do some maintenance on the prompts.

Less satisfying

I enjoy sharing my experiences by way of this blog, but the “feels like work” aspect sucks some of that fun out of the process. I no longer have the same sense of accomplishment when I press Publish like I recall having in the past. It’s more of a sense of relief that I’m finally finished with the damned post!

More learning

I feel as though having the robot editor review and edit the blog drafts gives me an external perspective on my writing. Having an editor who’s reviewed umpty-bazillion documents before mine can be a bit intimidating, yet instructive at the same time. In that sense it’s very much like the working with the best editors I’ve had in the past. Both I and my writing come out better for having the experience.

It’s comes down to trust

I think most of my feelings of unease stem from the fact that I don’t trust my AI editor at some level. Its confident evaluation the I did “X” which evaporates the instant I said, I did “Y”, to which it agrees just as enthusiastically is not confidence inspiring. This “No two answers are the same” property of LLM-GPTs seems like it should be a showstopper right out of the gate (a bias that likely comes from my decades of experience with the old, predictable computers and their crazy, deterministic algorithms). While, that’s a property that can be managed, it still leaves me a bit anxious.

I’m not ready to abandon my AI-overlord, er, I mean co-writer, just yet. We’ll keep working together to come to some level of agreement and, maybe even a level of trust.

But if I’m honest; the idea of having AI agents running un-checked is still nightmare fodder for me. Maybe that’s my next nightmare I need to confront and overcome?

Posted on

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.

Continue reading “Testing antagonistic AI review on my own writing”
Posted on

Finding the line between AI assistance and AI dependence

After six months of diving into AI tools, I’m still figuring out how to work with them without compromising my professional integrity. The old boundaries between my words and borrowed words don’t map cleanly onto AI assistance. When AI helps craft my prose, am I still the author? When my students use GPTs (a generative, pre-trained transformer, built on a large-language model, or LLM and more commonly known as an AI chat tool) to generate sophisticated responses, how do I know if they actually understand the material? The underlying tension in both contexts is the same: Where does human skill end and tool dependency begin?

I’ve been wrestling with this question through direct experience, using AI tools in my own writing and as I prepare to teach students about AI applications in technical writing scenarios. The uncertainty isn’t comfortable, but it’s productive. It’s forcing a clarity about professional standards that I previously took for granted.

The attribution gap

Traditional models for crediting intellectual work assume clear human sources. Plagiarism involves stealing and passing off ideas or words as one’s own without crediting the source. That creates a property line between what’s “my work” and what isn’t. The property line is fuzzy, but it’s recognized.

Work-for-hire contracts handle using another’s writing by transferring ownership. I might write the words, but my employer becomes “the writer” through legal assignment. Editorial assistance operates on a continuum: the greater the influence of dictionaries, grammar checkers, or human editors on the final product, the more they should be credited.

Search engines provide access to enormous amounts of knowledge while making attribution relatively straightforward. This makes it easy to build on others’ genius, and cite the sources to avoid plagiarism, while maintaining a clear distinction between your words and those of others.

But what’s a GPT in this context?

  • Is it a sophisticated grammar checker? Definitely.
  • Is it a mechanical editor? It can be.
  • Is it your personal writer-for-hire? It could be.
  • Is it a source of original content? Unclear.
  • Is it an industrial-strength plagiarism machine? That’s still a topic of heated discussion.

AI doesn’t fit into existing categories while somehow fitting into all of them. The academic press is still debating this. Stances range from “do what makes sense” to “no way, no how” depending on the field and editorial board. Most of my academic papers were guided by ACM and IEEE standards, so the ACM’s more flexible approach feels familiar and reasonable while maintaining academic transparency.

The competence question

As a writer, the integrity question centers on authorship: “Am I still the writer if AI helps structure my arguments?” As an instructor, it’s about learning: “Do my students understand the material if they’re using AI to generate responses?”

Continue reading “Finding the line between AI assistance and AI dependence”