FAQs are not the answer

Writing for LLMs is the new SEO obsession. Not a day passes without seeing some question popping up in tech writing communities about how to best compose content for AI scrapers. Folks even wonder if a different style guide should be necessary, or whether tables should be avoided because they’ve seen a pull request rejected in a Microsoft...

I think all technical writers, at some point or another, feel the urge to base their work on something more systematic than “it’s just the way folks documented stuff since forever”. Toolkits and frameworks provide content types, which is immensely valuable when you know what you want to write, but starting from there is like buying a hammer...

For the first time since I started this blog, I’m writing some predictions on software technical writing for next year. Not because I think they’ll be accurate—they never are—but because the exercise reveals what we’re concerned about and what we hope to tackle. Predictions are to-do lists in disguise: they highlight challenges we’re determined...

I’m a terrible user of documentation. I tend to consume docs in a hurry, reading diagonally, Control+Fing my way to things. I generally mistreat the interface of docs until I obtain something resembling an answer. I do this because I’ve little time and I need to fix issues fast. I love examples I can copy and paste. I’ve little patience for...

I recently was a guest on The Stack Overflow’s Podcast today, talking about docs (of course), the Vale prose linter, job titles, automation, LLMs, and much more. You can listen to the entire episode here or in the SO blog, or read the transcript. Getting docs closer to developers was one of my personal goals this year, and I think these kind of...