Updates to my coffee, car-buying, and zero-drop shoe posts, plus my Jekyll documentation theme
I don't often update previous posts, but I recently updated four things I really wanted to revisit. I went back to drinking coffee, returned the Honda Civic mentioned in my car-buying post, stopped recommending zero-drop shoes for calf strains, and released a new version of my documentation theme for Jekyll, which now looks more like idratherbewriting.com. Read more »
Documentation at Scale with Andrew Etter: Ten years after Modern Technical Writing
In this podcast, I chat with Andrew Etter about his new book, Documentation at Scale: Best-in-class content for the AI era, the follow-up to his 2016 book Modern Technical Writing. We discuss why Markdown's simplicity still matters and what its variants have lost, why the case for a docs team rests on accountability rather than writing every word, a Slack bot that lets non-technical contributors open docs PRs, how AI shifts writers toward higher-level work, and where AI still falls short with tutorials and video. Read more »
Agent readability: Carrying over top-level page notes into independent chunks
Of all my articles on agent readability, none has attracted as much attention as Chunking your content for agent readability, probably because chunking raises so many hard problems for tech comm. One problem I haven't explored yet is how to carry top-level page notes, such as deprecation status, availability, release stage, and version numbers, into the later chunks of a page. Chunks that are disconnected from those notes can still be retrieved, recommended, and used by agents as if the notes didn't exist. Read more »
Mastering API Documentation with AI (Sponsor)
Mark Wentowski is teaching his live API documentation course again this fall at docsgeek.io. It is his course, on his own site — separate from the API doc course here.
The fall cohort starts October 19: seven 90-minute classes, Mondays 8:00–9:30am PT, running through November 23. Recordings come with every enrollment if you cannot make a session live. New this time is an optional AI add-on, where you use Claude to draft API flow guides and OpenAPI descriptions, then validate the output against the live API.
Code TOMAPIS takes $250 off. See the full syllabus and schedule. Enrollments through that code earn me a commission.
|
