I'd Rather Be Writing Blog and API doc course
Stay updated with best practices for technical writers. Includes an API documentation course for technical writers and engineers learning how to document APIs. The course includes sections on what an API is, API reference documentation, OpenAPI specification and Swagger, docs-as-code publishing and workflows, conceptual topics, tutorials, API documentation jobs, and more.
- Website
- idratherbewriting.com · all feeds from this site
- Feed URL
https://idratherbewriting.com/feed.xml
Read it in your FeedListing reader
Or add to: Feedly Inoreader Raw feed
Latest posts
-
Chunking your content for agent readability
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…
-
Looking at a site like an agent — identifying semantics in styling
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…
-
Making documentation pages agent friendly
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…
-
My AI strategy to fix docs based on chat logs
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.
-
AI Book Club recording of Project Maven: A Marine Colonel, His Team, and the Dawn of AI Warfare, by Katrina Manson
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…
-
Why docs still need an owner — podcast with CT Smith about WTFM
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…
-
How I turn my API doc course into a PDF and sell it on Buy Me a Coffee
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…
-
Building machines that work with other machines
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…
-
Building out my agent skills course and rethinking product skills
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…
-
AI Book Club recording: I Am Not a Robot by Joanna Stern
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…
-
Six new books in tech comm: a roundup
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…
-
Buying a car in the age of AI
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…
-
Why biking to work fails when commuting from Renton to Seattle
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…
-
Writing for an audience of agents — podcast with Ethan Palm from Mintlify
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…
-
Review of The MANIAC, by Benjamin Labatut -- thoughts on logic and the end of play
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…
-
AI Book Club recording of The MANIAC by Benjamin Labatut
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…
-
Reflections on Ai4 conference - some absences from a tech writer's POV
This week I attended Ai4 , promoted as the largest AI conference in North America. It was held at The Venetian in Las Vegas and lasted 3 days. The conference had more than 12,000 attendees (from 100 countries), 400 exhibitors/sponsors, 1,000 speakers, 700 sessions, keynotes from…