Recent content on passo.uno
Ninth episode of the AI & Docs podcast series is up! In this one, Tom and I talk with Sarah Deaton, a technical writer at Anthropic, about what documentation work looks like when automation handles most content generation: shifting from writing to orchestrating, mining AI assistant conversations for gaps, building forensic processes for accuracy claims, and managing high-volume PR pipelines…
A friend of mine recently lost her job in a layoff. She looked at her résumé with a pang of despair and asked me for advice on what she should learn next. She hasn’t thrown in the towel on technical writing yet; she wants to find another tech writing job, despite the prevailing pessimism that besieges our craft. How does one upgrade to, say, content engineering , she asked.
While chatting with Sarah Deaton about the formats agents could use to talk to each other, we got to questions that might sound obvious: why should machines (say, LLMs) communicate with each other like we do? Do they need all the rhetoric we carry around? Or could they get by with a terser register, one that carries the same meaning but in far fewer tokens?
Docs as code used to mean editing docs as if they were code. Today it also means that docs have become executable , either as agentic instructions, skills, or context for large language models. Tech writers must now ensure that the reference and procedures they’ve carefully written and edited are the best possible fuel for AI, lest they jam the machine or make it stray into dangerous territory.…
In my predictions for 2030 I wrote that tech writers would be using specialized LLMs, running locally on powerful hardware. I see hints of this move to “local first” among engineering pundits, but we’re not there yet, in part because of how much more powerful connected frontier models are. That doesn’t mean we can’t experiment, though. That’s precisely what I did last week, trying to fine-tune an…
Eighth episode of the AI & Docs podcast series is up! In this one, Tom and I talk about what makes documentation genuinely beautiful versus merely functional, how Calvino’s literary principles apply to docs, why our role is shifting from creating to judging AI-generated content, the psychological toll of endless review work, and why most hastily-built tools lack the craft to last. 
 You…
I joined Patrick Bosek on the Behind the Docs podcast to talk about what AI actually means for technical writing. We covered the evolving role of tech writers as architects of tooling and content systems, why AI works better as a collaborator than a replacement, the tension between moving fast and implementing thoughtfully, the case for local and self-hosted models, and why great docs in the…
Back in 2024 I wrote that AI helps me remove boring work at the margins. This is fine for a lone writer, but how to scale this to an entire team of technical writers? How to make the system helpful but not intrusive? These are all questions I’m starting to answer now, partly through experimentation, but also through dialogue with practitioners and colleagues. One answer I’m testing these days…
AI is inflicting a proliferation of tools, in the utensils’ sense. Folks are conjuring all sorts of programs out of thin air, unrestrained. Someone confessed on Hacker News to having created a hundred custom utilities. Linked to this increase is the promotional noise: Not a day passes without someone claiming they’ve made a tool to solve a fundamentally silly problem in some subreddit thanks to…
Docs are often thought of as a purely functional artifact, a packet of content that, when it works, it’s not remembered at all. Those who consume docs, however, can tell whether a manual or docs site pleases their mind and senses in ways that others don’t. We know the feeling of a page that lands and the feeling of a page that drags. 
 Now, if we agree that docs can be a product, why not seek…
Seventh episode of the AI & Docs podcast series is up! In this one, Tom, Larah Vasquez, and I talk about local LLMs and the shift away from API dependence, why AI output is bad by default, skills as a token-efficient alternative to stuffing everything into MCP servers, the memory problem in LLMs, and whether tech writers are quietly architecting themselves into a higher role — or out of one.
Three years ago I published a high fantasy map of technical writing . The world has moved quite a bit since then. AI happened, and with it a darkness has crept in from the north, one that feeds on the daily pessimism of writers that feel cornered. 
 I felt like an update was long overdue, so I sat down, fired up an editor and created a new version. It’s a map of contested territory, and…
If someone asked me to set up a team in charge of software documentation, I would not hire for specific roles or cookie-cut job descriptions. Professions tied to knowledge buckets are bound to shrink or disappear. Instead, I would hire people that could move freely between four quadrants, each defined by the proximity to a focus pole and its skills. The poles in this team setup would be the…
Sixth episode of the AI & Docs podcast series is up! In this one, Tom, Manny Silva, and I talk about documentation testing (the deterministic kind), skills files and why they matter, the ethical tension of externalizing your expertise, and the evolving role of tech writers as content curators. Or, if you prefer the romantic version, guardians of knowledge. 
 You can watch / listen to the…
Not a month goes by without someone claiming they’ve killed tech writing. A few weeks ago, it was CodeWiki and its docs theatre . Now it’s the turn of Claude Skills and their ecosystem of Markdown instructions served as if they were executable code or macros. Docs, though, are tougher than they’d expect, because they’re the strongest signals in a sea of noise, and because they’re pretty much…
At the end of The writing was always the cheap part , I alluded to the fact that tech writers need to pick up new habits and skills, but didn’t dig into what that entails. These days, any LLM can put together plausible docs with some context and a simple prompt. So what is it that a tech writer should be learning now? Despite the fact that the AI landscape is ever shifting under our feet, I should…
Last December, quite unrealistically, I took a solemn oath: I would not write again about AI for at least another year. I was growing tired with the incessant noise, the lack of stability, and the self-imposed stress of keeping up with all the attention we must spend on factoids such as how well an LLM can draw a pelican riding a bike, which bury the important aspects of our craft as if they were…
Fifth episode of the AI & Docs podcast series is up! In this one, Tom and I discuss our predictions for tech comm in 2026, the evolution of writers into automation engineers, the risk of the Reverse Centaur dynamic, and the growing value of authentic human connection. 
 You can watch / listen to the episode here: 
 
 https://idratherbewriting.com/blog/predictions-2026-tech-comm-podcast…
I like cooking recipes. They’re clean, serene documents where, at some point, one or more utensils enter the stage to perform a task. If you were to write one on how to use AI to augment your work as a technical writer, though, you would have a hard time deciding when and where LLMs come out of the toolbox to aid you. The variety of flavors in which AI presents itself doesn’t help. This is why…
Hey you, 
 Yes, you, who are thinking about not hiring a technical writer this year or, worse, erased one or more technical writing positions last year because of AI . You, who are buying into the promise of docs entirely authored by LLMs without expert oversight or guidance. You, who unloaded the weight of docs on your devs’ shoulders, as if it was a trivial chore. 
 You are making…
Fourth episode of the AI & Docs podcast series is up! In this one, Tom and I chat with CT Smith about AI workflows, building tools that don’t depend on AI, the fear of skill atrophy, living intentionally offline, and why the line between developer and writer is starting to blur.
Instead of writing my tech comms predictions for next year like I did in 2024 , I’ve written a fictionalized account of my day as a technical writer in 2030. It’ll be interesting to see whether we get there or not. Take it as a window into a possible future, one where AI usage is safer, more regulated, and better integrated with our workflows (as it should be).
Third episode of the AI & Docs podcast series is up! In this episode, Tom and I talk about documentation theatre, benchmarks for AI, productivity metrics in the AI age, and much more.
Code Wiki , a new AI tool by Google, claims to generate a complete set of docs, including diagrams, from code repos. The landing page goes as far as saying “Stop documenting. No more stale docs. Ever”, a claim that made me stagger and reach for the nearest chair. 
 That these tools are laughably bad isn’t reassuring; their emergence hints at a deeper and more unsettling cultural problem.
The dam of AI-written doc contributions might be about to break. It’s already cracking for code, with posts wondering how to review a vibe-coded pull request consisting of nine thousand new lines of code. In the midst of what Tom Johnson describes as acceleration , docs-as-code writers wonder how to contain the seemingly inescapable wave that could bury their backlogs in AI slop. The answer could…
I really enjoyed speaking at Write the Docs Berlin this year. My talk was a bit special, a message in a bottle for writers who are struggling — for anyone who’s struggling in their careers, really. Here are the recording and the slides, as well as some links to the content that inspired the talk. I hope you’ll find it useful.
Second episode of the AI & Docs podcast series is up! In this episode, Tom and I talk about MCP servers with Anandi Knuppel. As Anandi says, “wherever there are words with regards to a technical product, that’s the technical writer’s domain”. Don’t miss it!
If you’ve been following the AI space for a while, the MCP acronym might be a familiar sight: it’s an open standard for connecting large language models (LLMs) to tools and data. Without the ability to use tools and get data, AI agents are powerless, their knowledge limited to their training set and the context at hand. Giving in to my curiosity, I created an MCP server to demystify this piece of…
Kate Mueller’s The Not-Boring Tech Writer is one of my favorite tech writing podcasts. In Growing as a technical writer in the AI era , Kate and I talked about the Seven-action Docs Model and how to grow as a tech writer. Don’t miss it!
It’s official! Tom Johnson and I teamed up to start an AI & Docs podcast! We had this idea brewing for a while and finally got to record the thing.
You might have read Annie Mueller’s post poking fun at developers’ tutorials. If you haven’t yet, do it now. On the surface, it’s an exquisite rendition of the kind of technobabble we tech writers get to tame every day. Reactions among devs ranged from nervous snickering to outright shame. Like all the best parodies, Annie’s goes deeper than that, though: It puts a finger on…
I sometimes lurk on /r/technicalwriting to gauge the interests and sentiments of the community. What I’ve noticed over the years is that pessimism and anxiety have always been quite high; Reddit, it seems, can be a powerful outlet for all sorts of feelings. Here I’d like to analyze and address some of the challenging ones. If you had similar thoughts, I hope my words will prove useful.
Docs are a product. Contributing to them is among the finest forms of product engagement. Bystanders can become builders and authors: They contribute a verse so that the powerful play can go on. They cease being the product to become the owners of the product narrative. And in this AI age, where docs matter more than ever , users who write can steer the future of products.
I’ve been noticing a trend among developers that use AI: they are increasingly writing and structuring docs in context folders so that the AI powered tools they use can build solutions autonomously and with greater accuracy. They now strive to understand information architecture, semantic tagging, docs markup. All of a sudden they’ve discovered docs, so they write more than they code. Because AI…
Today I discussed how tech writers can use AI at work with Tom Johnson and Scott Abel . It all started from my post What’s wrong with AI-generated docs , though we didn’t just focus on the negatives; in fact, we ended up acknowledging that, while AI has limitations, it’s also the most powerful productivity tool at our disposal. Here are some of the things I said during the…
I’ve been writing documentation and technical articles for more than a decade now. One piece of feedback I consistently got from managers and peers during all these years is how fast I am when producing and releasing docs. For example, I was once asked to document a new feature from a team I wasn’t serving two weeks ahead of launch. Everything was new to me, but I had most of the docs drafted…
Strategy, Michael Porter wrote , is choosing what not to do. Now, the problem with knowledge work such as the one tech writers carry out is that it’s full of things that seem to require equally important, time-consuming decisions. While engaging in lengthy disquisitions might be alluring, endlessly combing the Zen garden of theory doesn’t solve the basic problem of the docs hierarchy of needs ,…
This last weekend I created another LLM-powered tool, Impersonaid (all puns intended). It’s a docs user simulator: you provide the URL of a document (or its Markdown source), select the virtual persona, and start a conversation about the content. Right after I released it, I realized that I had been talking to an imaginary friend to create more fictional interlocutors to interact with. It’s not as…
A colleague recently asked how I find time to blog about technical writing after hours. The answer is surprisingly simple: I prioritize writing above other things. I could have posted that exchange on social media and called it a day, but there’s more nuance to that simple reply. Let me elaborate, it might be useful.
I spoke at the betterCode() ArchDoc 2025 conference a couple of weeks ago about the Seven Action Documentation model . It was a very nice experience and I thank the organizers for inviting me and letting me post the video. Here is the full recording of the presentation (it’s about 40 minutes long):
We all want to do a good job. Some of us also want to get better at our craft for a number of reasons, either practical or slightly delusional. Those include getting a raise, strengthening our résume, or simply ending the day with a fragile feeling of satisfaction after surviving failure for the nth time. They’re all good goals, though the ways of achieving them are not always straightforward.…
While some developers wrinkle their noses at the sight of Copilot and similar AI-powered tools, tech writers find them to be great sidekicks. Creating a script to automate edits or content migrations takes at most a few minutes of tinkering. The same goes for code examples and snippets for dev documentation, docs sites’ enhancements, and even wacky experiments in retrocomputing. With local LLMs…
I’ve recently upgraded some of the hardware I use for work and leisure, so it’s a good time to refresh my list of tech writing gear . At the same time, after working as a documentation engineer, I also picked up new favorite tools , especially AI-powered ones. Some I already use at work, while others I keep for personal projects. Let me tell you of some of the recent additions to my personal…
In what is tantamount to a vulgar display of power , social media has been flooded with AI-generated images that mimic the style of Hayao Miyazaki’s anime. Something similar happens daily with tech writing, folks happily throwing context at LLMs and thinking they can vibe write outstanding docs out of them, perhaps even surpassing human writers. Well, it’s time to draw a line.…
Demoralized by the advent of LLMs, I see tech writing communities break ranks and flee. In a world where coders who write seem to muster more respect than writers who code, the response from tech writers to the challenges posed by the intersection of automation, multichannel delivery, and docs-as-code is weak, if not absent. Conferences and blogs mostly focus on soothing anxiety and perfecting…
The part of my brain that rages against injustice stirs like a slumbering dragon when I read the words “Native English”. As a speaker of English as a second language, I find native to be a rather inadequate, if lazy, choice as an attribute meant to describe linguistic proficiency. You’re born with eyes, but that doesn’t automatically make you a competent watcher; you acquire a…
This past weekend I’ve been experimenting with AI-assisted coding to port basic docs-as-code elements to old operating systems and platforms, such as the venerable Intel 386. While this might strike you as a bizarre display of futility, I find this sort of retrocomputing exercise to be quite beneficial, if not enlightening. Something just clicks when you stop and walk backwards.
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 repository on the silliest grounds.
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 without knowing that half of the work you’ll do is…
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 to overcome. Plus, they’re fun to write. So here are…