Docs by Design

AI agents routinely skip content when reading documentation, grabbing just enough to generate an answer.

A year of integrating AI into an API documentation course revealed three durable categories for thinking about AI in technical writing—supporting content, generating content, and writing for AI readers—plus three principles for deciding when to use it.

"MCP" was everywhere and I had no idea what it actually was — and I teach API documentation.

AI tools need the same accessibility practices that serve vision-impaired readers: descriptive alt text, complete transcripts, explicit visual descriptions.

Code examples need pedagogical principles that help human developers: progressive complexity, clear syntax, explicit comments, authentic errors.

AI needs writing quality that serves humans: clear topic sentences, explicit connectives, concrete nouns, consistent terminology.

AI tools need information architecture principles technical writers have used for decades.

Reflecting on adding AI tools to my API documentation course, I discovered that when students can generate content faster with AI tools, your evaluation processes need to keep pace, or problems can multiply quickly.

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.

After publishing my last post, I asked Claude what it thought about it, using the “reflective blog post” prompt I’ve been developing.