A couple of weeks ago, I wrote about a documentation strategy I'm pursuing: mining chat logs from AI app builders to find doc problems and fix them in a continuous loop. In this post, I'll go deeper into the obstacles I faced when I looked at the logs, and describe a clever workaround — simulating the same user queries but asking the agent to document a build log — that turned out to be more useful than the logs themselves.
Nytril is a document authoring tool built on its own programming language, where text, data, calculations, and formatting all live in source code that runs to produce documents. In this sponsored Q&A, Shawn McCreight answers 10 questions about who Nytril is for, how it compares to DITA and Flare, how writers get started, where data comes from, output formats, localization, docs-as-code workflows, AI, and pricing. Shawn wrote his answers as a Nytril program, so this post also includes the PDF, DOCX, HTML, and source code that program produced.
This post continues my series on agent readability by looking at chunking. When docs are ingested into an MCP server or other retrieval system, a chunker splits each page into passages, and the agent often sees only those passages rather than the whole page. I walk through how ingestion works, how one chunker (Google's Agent Search) sizes chunks in tokens, and how headings, section length, long tables, long code samples, images, procedures, and tabs hold up when a page gets chunked.
Following up on my previous post about content that loads through JavaScript, this post looks at another agent-readability problem: styling that carries meaning. When gray text marks a module as excluded from a product tier, or a check-mark icon means included, that meaning disappears once an agent fetches the page and converts it to Markdown. I walk through how to compare the human view of a page against the agent view, and why complex tables and elaborate HTML layouts matter less when agents read basic Markdown.
This week I'm working on making our doc site agent friendly. Most agents read pages through fetch tools that don't run JavaScript, so content that loads only when someone clicks is invisible to them, while content that's merely hidden with CSS still comes through. Long pages are another problem, because agents truncate them and then fill the gaps with guesses. This post covers which JS patterns can stay, why long pages need splitting, and how I set up a Markdown mirror with a Cloudflare worker.
My strategy for improving docs has two stages. First, turn the failure points in AI chat sessions into actionable doc tickets. Second, fix those tickets with a skill that applies a tech writer's judgment, and use evals to check whether each fix worked.
This is a recording of our AI Book Club discussion of Project Maven: A Marine Colonel, His Team, and the Dawn of AI Warfare by Katrina Manson, held October 18, 2026. Ratings ranged from two stars to five, but most of the group agreed the book made AI warfare feel immediate rather than futuristic. We talk about how much of the kill chain is information work long before anyone fires a weapon, moral injury among remote operators, the habit of clicking allow on every permission prompt, who's to blame when an AI-identified target turns out to be a school, AI-driven propaganda, bureaucracy as a safeguard, and what a book like this can't tell us.
In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with CT Smith about her new book, WTFM: A Practical Guide for Standing Up Docs at a Startup. We discuss why docs need a human owner even when anyone can generate content with AI, how CT kept her voice by writing the book herself in Neovim, the layered pipeline of Vale hooks, skills, model reviews, and sandbox fixtures that lets Claude Code handle about 40% of her tickets, the risk of gradual disempowerment, and why systems thinking matters most in a first docs hire.
My API documentation course is free on the web, but I also sell a PDF version of it through Buy Me a Coffee. This post walks through each step of how I turn about 170 web pages into a 975-page PDF with chapter files, including the print configuration, layout, CSS, table of contents, Prince build, chapter splitting, file hosting, and the Buy Me a Coffee setup. This post is mainly a technical how-to in case anyone else wants to do something similar.
In the past couple of months, my focus as a tech writer has shifted from writing to building machines, which in reality are elaborate skills that do things. One skill triages incoming bugs and website feedback on an hourly schedule, and another analyzes AI chat logs to recommend documentation improvements and hands its bugs off to the triage skill. This post describes both skills and reflects on documentation logistics, comparing them to the many processes that keep a city running.
I've been adding to my agent skills course, including a reworked section on product skills that now takes a docs-first stance after I started seeing log data. I've also been leaning on AI more heavily to write the course content, which seems fine for instructional material that's constantly in flux. Writing with AI pushes me toward ideas I hadn't considered, so it's become a way to learn while writing, even if I have to course correct along the way.
This is a recording of our AI Book Club discussion of I Am Not a Robot: My Year Using AI to Do (Almost) Everything by Joanna Stern, held September 20, 2026. The group gave the book its lowest ratings yet, and much of the discussion is about why: so many of the experiences come across as superficial stunts with AI, rather than true engagement. In our discussion, some found the medical chapter to be the book's strongest section. Other topics: the question of whether you should fix a system before amplifying it, chatbots that give you the candid career advice your friends won't, school policies on AI and who tutoring actually serves, work threads where both sides are pasting from AI, and the line between removing drudgery and giving away the thinking.
Six new books have recently been published in tech comm, and I wanted to round them up in case you missed some of them in your news feeds. The books include WTFM by CT Smith, Documentation at Scale by Andrew Etter, the second edition of Docs for Developers, Docs as Tests & AI by Manny Silva, Women in Technical Communication edited by Sharon Burton, and Technical Communication and the Discipline of Content by Rebekka Andersen and Carlos Evia. This post gives some brief factual details about each book, drawing on the jacket copy, with links, covers, and publication details.
One thing I'm not great at is buying cars. I'm incredibly indecisive, in part because historically I have regretted some of the cars I've purchased. Hence, I'm afraid of buying the wrong car, and so I vacillate endlessly to an almost neurotic degree. Also, buying cars is tough because you have a limited number of test drives — test drives require visits to dealerships and lots, and you don't have unlimited time and patience at these places.
In an attempt to get to work without a car, I tried three bike + transit routes from the Fairwood area of Renton to South Lake Union in Seattle. Each one took too long (~ 2 hours) and involved too many car-centric stretches. Here's what I learned about why bike commuting fails from Renton, and how my plans evolved.
