Recent posts from the tech docs community
50 recent posts
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 recomme...
Keeping API documentation accurate is harder than writing it. Code evolves while documentation lags behind, resulting in outdated, inconsistent references. Developers end up reverse-engineering endpoints, implementing incorrect integrations, or abandoning APIs entirely because...
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 tha...
A 60-second motion design video costs $3,130 to commission. Here's the exact process I used to make one with Claude in a day: the story, the scene-by-scene storyboard, and the assets that keep it from looking like AI slop.
Here is a situation most documentation teams recognize. The product ships its first release, the manual is written, everything is in order. Then a Professional edition appears. Someone duplicates the manual, makes the relevant edits, and moves on. Then an Enterprise edition. T...
Hi, everybody! Aaron and the rest of the newsletter team are back to bring you a roundup of interesting conversations from the Write the Docs community.
Every documentation site has an AI agent and a human reader nowadays, where AI agents are dominating the number of requests sent to the server to fetch a docs…
Whilst AI is changing documentation work, organisations are seeing very different results. The most successful results come when you know what you ultimately want AI to achieve, and what “good” looks like. In an organisational context, you also need to know where A...
Your résumé lists what you did. It doesn't explain why it matters or where you're headed. In this issue, you'll build a short story you can say out loud in about 30 seconds that explains who you are, what you offer, and what you're looking to do next. Have a Better Answer to "...
When a company adds its second product, documentation stops being a content problem and becomes a structural one. Someone has to decide what customers see separately, what the team maintains once, and who owns the section that both products depend on. I spend a lot of time loo...
OpenAI has announced dots, a new type of always-on AI agent that can continue working between conversations. Most AI assistants wait for a prompt. A dot can be given an ongoing area of work to monitor. A dot has its own cloud computer and browser. It can use connected applicat...
Cherryleaf’s Ellis Pratt will be speaking at Techsmith’s “Build an AI-Ready Workforce” webinar. AI is changing the way we work, but successful adoption takes more than just new tools. In this Unlocked follow-up session, Dr. Gleb Tsipursky, AI adoption e...
We’ve built an online exercise: Three teams. Three sets of docs for the same feature. Zero agreement on which one is correct. See if you can spot where this documentation process falls apart? The exercise is embedded below or you can use this link to the exercise. The po...
We have been researching the different AI documentation workflows technical writers use, as part of the development of our new Managing documentation projects with AI e-learning course. We posted our initial findings to a forum, and a few people responded with dazed eyes emoji...
My husband likes to say “prompts aren’t guardrails,” and it’s been ringing in my head for months, so I figured I’d finally write down my take on it. I regularly see people who are frustrated, or kind of confused, because they told an LLM very emphatically (in ALL CAPS! Repeate...
Why Tech Writers Need to Know Their Reader In the industry of technical writing, ignoring the reader can be compared to professional malpractice. “Universal documentation” is a term that does not actually exist, as IT readers range from fresh graduates tackling the...
Two conversations this month sent me back into my server logs. The first was the ongoing industry debate about whether llms.txt does anything, which flares up every time a well-known project adds one or removes one. The second was a colleague mentioning that answer engines and...
There is a idea doing the rounds: AI becomes less visible when people can break their work into well-defined tasks and delegate those tasks to thousands of capable helpers. The claim is deliberately provocative. Most people do not literally have 10,000 agents working for them....
On the comparable sources, the September 2026 results looks very similar to August, with a slight softening in permanent/open vacancies. September doesn’t show a major deterioration in demand for technical communicators. It’s another broadly stable/slightly down mo...
AI can produce documentation drafts quickly. But hard problems remain, such as deciding which product changes deserve documenting in the first place. When a product changes, some, but not all, of those updates need a documentation update. Someone has to make that call, find th...
A colleague asked me this week how I've built the things I've built over the past year: the Agent-Friendly Documentation Spec, the afdocs checker, agentsummons and agentminutes, Agent Skill Implementation, the Agent Reading Test. He characterized it as "just prompting,&qu...
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...
A technical writer asks an AI tool for a favor: “Draft documentation for feature X” — a feature that shipped to users three weeks ago. The tool returns a polished, well-structured draft in under a minute. It reads like professional, natural human writing, and it fi...
A hands-on look at what I learned designing four specialized Rovo agents and an orchestrator for a Confluence knowledge base.
AI is reshaping technical writing, and our Using Generative AI in Technical Writing course has been refreshed to keep pace. Nearly 50 videos have been added or updated for 2026/7, building on the 40+ optional online practice exercises introduced earlier this year. The course w...
Release notes and changelogs are core artifacts in modern software development that communicate what has changed between versions. Release notes are typically written for end users and highlight meaningful updates, improvements, and fixes in a clear, non-technical way. Changel...
In mid-to-late June 2026, Read the Docs experienced the largest and most sophisticated distributed denial-of-service (DDoS) attack in our history …
Whoever speaks badly, thinks badly and lives badly. We must find the right words: words are important! —Nanni Moretti A reader reached out to me the other day to talk about the future of tech writing as a profession. They asked me a pretty good question: What skills would yo...
Can you spot what’s going wrong in this thread? It’s a Slack conversation showing how one team documented a new API endpoint. It looks routine. It isn’t. Try tagging the issues yourself: The exercise is embedded below or you can use this link to the exercise....
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 &...
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...
Expo Router's submodule NativeTabs renders a real Material 3 navigation bar on Android and its native counterpart on iOS from one component tree.
Not everyone agrees on what's important in their documentation! My hierarchy does not fit everyone's needs.
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...
What Are Product Specifications? In practice, a product specification is a structured document (or set of documents) that defines what a product must do and how it should behave. It answers core questions such as: A specification acts as a single source of truth during design,...
In this podcast, co-host Fabrizio Ferri-Benedetti and I chat with Ethan Palm, a technical writer and knowledge engineer at Mintlify, about what happens when nearly half your documentation traffic comes from AI agents. We discuss Mintlify's platform data on agent versus human t...
Unfortunately, the best laid plans of mice and men may still go awry, and my life took a weird turn.
Issue 56 A broken step in a tutorial costs more than one frustrated reader. In this issue, you'll explore how working code turns into a broken draft, and how a full technical test protects your readers and the trust they place in you. And then you'll explore Podman, an alterna...
How I extended my blog's semantic search to cover content I've published outside the blog.
These days I am spending more time in the terminal app than any other environment on my development machine.
Six Months Later
Two dictionaries independently picked the same word of the year for 2025: slop. Merriam-Webster defines it as digital content of low quality, produced in quantity by artificial intelligence. Macquarie went with “AI slop” and added a detail I keep thinking about: co...
A few weeks ago I ran isagentready.com on docs.expo.dev, a site that I manage and work on, for my day job.
We recently read The MANIAC, by Benjamin Labatut in my AI Book Club. This was our first work of fiction, though much of the text is imagined biography, so not really traditional fiction. It reads more like a collection of short biographical facets, connected thematically but l...
One question keeps coming from customers running multilingual docs through machine translation: why does the same term come back different across languages, or even across their own topics? To understand where terminology drift comes from and how teams can prevent it, we...
Being able to single-source technical documentation is arguably the main perk of modern technical writing tools. ClickHelp is among those help authoring tools that offer their clients various ways to single-source content. Single sourcing means that the same documentation proj...
I’m seeing more instances of docs and README files addressing agents directly, as in “Hey, if you’re an agent, follow these instructions”. In some cases, those instructions are visible to human readers as well, which makes for a deeply awkward experience, the reading equivalen...
Last time when I started to write this post, I got carried away. My brain was on verge of explosion because Claude and I had worked together on so many…
This is a recording of our AI Book Club discussion of The MANIAC by Benjamin Labatut, held August 16, 2026. This was the club's first work of fiction, and much of the discussion is about what that mode makes possible: getting inside the madness of scientists like John von Neum...
Last week, I wrote the words “reader as actor” about 200 times in PR reviews. I updated a few skills and reworked lots of sentences around this theme. Making sure the reader is the actor in the docs is my newest obsession, the latest sentence-level nit I’ve started noticing ev...