The Evolution of Documentation Practices

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...

Everybody loves to hate Frequently Asked Questions, or FAQs. More often than not, technical writers pale and stagger at the sight of hefty, unsorted FAQ sections, as if they were beholding a writhing mass of primal chaos. Others value their pragmatic qualities: FAQs, they say, lower the bar to contribution and are good fuel for LLMs and search...

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...

A reader asked me how they’d become a Documentation Engineer, because they saw I got hired as one and felt curious about what it takes to get there. This inevitably got me thinking about job titles and the evolution of tech writing, two topics that are quite central to this blog. Let me begin with the short answer: As a tech writer you’ll have to...