passo.uno

Skills are docs, and docs need tech writers

Sun, 08 Mar 2026 14:00:00 +0000

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 everywhere. Including, well, skills.

New habits for tech writers in the age of LLMs

Sat, 28 Feb 2026 15:00:00 +0000

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 be able to give you some actionable directions. Buckle up.

The writing was always the cheap part

Tue, 24 Feb 2026 21:00:00 +0000

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 mere prompt flourish. With my passionate epistle, I thought I’d said all I had to say. I was wrong.

Episode V of Phase One: Tech comm predictions for 2026

Mon, 26 Jan 2026 07:00:00 +0000

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

Some of the things I said:

The four modes of AI-augmented technical writing

Sun, 25 Jan 2026 11:00:00 +0000

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 I’ve come up with a framework that describes applications of the different AI tools at our disposal.

To those who fired or didn't hire tech writers because of AI

Mon, 12 Jan 2026 11:00:00 +0000

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 a big mistake. But you can still undo the damage.

Episode IV of AI & Docs: AI tools, automation, and an intentionally offline life

Mon, 05 Jan 2026 07:00:00 +0000

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.

[Experiment] I interviewed Claude and Gemini about my 2025 blog posts

Sun, 21 Dec 2025 15:00:00 +0000

I never posted so much as in 2025. Instead of analyzing my own blog production, I chose to interview Claude Opus 4.5 and Gemini Pro 3 about it and get their predictions for next year (with a surprise guest). They never said “You’re absolutely right”, which is reassuring. They were also quite humorous at times. I had a blast co-writing this with them.

My day as an augmented technical writer in 2030

Sat, 13 Dec 2025 16:00:00 +0000

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

Episode III of AI & Docs: Docs theater and the acceleration paradox

Mon, 01 Dec 2025 08:00:00 +0000

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 wikis are documentation theater as a service

Sat, 15 Nov 2025 12:00:00 +0000

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.

You need an AI policy for your docs

Mon, 10 Nov 2025 15:00:00 +0000

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 lie in taking a stance. This means crafting an AI policy for docs.

Failing Well: A Practical Guide to Growth for Technical Writers

Thu, 06 Nov 2025 08:00:00 +0000

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.

Episode II of AI & Docs: MCP and the role of tech writers

Mon, 27 Oct 2025 05:00:00 +0000

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!

Why I built an MCP server to check my docs (and what it taught me)

Mon, 13 Oct 2025 15:00:00 +0000

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 tech and gain a better understanding of its potential.

Not all is rosy, but if there’s a place where doc tools need to grow, it’s this.

[Podcast] Growing as a technical writer in the AI era

Thu, 02 Oct 2025 14:00:00 +0000

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!

First episode of the AI & Docs podcast is out!

Mon, 29 Sep 2025 08:00:00 +0000

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.

When docs become performance art, everybody loses

Wed, 24 Sep 2025 14:30:00 +0000

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 “documentation theater”, a state where docs are performative and not addressing a need nor caring about it. Let me explain why I think writing docs because you are forced to is worse than not having docs at all.

The future is open: Answering the most common tech writing worries

Sun, 14 Sep 2025 16:00:00 +0000

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.

Contributing a verse: When users become documentation authors

Sun, 31 Aug 2025 13:00:00 +0000

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.

AI must RTFM: Why technical writers are becoming context curators

Fri, 08 Aug 2025 14:00:00 +0000

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 must RTFM now.

Webinar: What's Wrong with AI Generated Docs

Thu, 24 Jul 2025 20:00:00 +0000

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 webinar, transcribed and edited for clarity.

How I write docs quickly

Mon, 21 Jul 2025 12:00:00 +0000

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 after four days. By launch, the docs had been deemed ready to go live.

Things technical writers shouldn't care about... yet

Mon, 23 Jun 2025 13:00:00 +0000

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, which is writing the damn docs and making sure they’re accurate and useful.

Conjuring digital companions: How I'm thinking better through AI

Wed, 18 Jun 2025 15:00:00 +0000

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 bad as it sounds, though. In fact, I would argue this is what writers are meant to do.

On finding time to write (this is not productivity advice)

Sat, 07 Jun 2025 15:03:00 +0000

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.

Beyond Content Types: A Human-first Model for Technical Documentation

Wed, 28 May 2025 11:00:00 +0000

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):

How to grow as a technical writer

Sun, 18 May 2025 15:00:00 +0000

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. Moreover, the path to career growth is riddled with self-doubt and impostor syndrome.

Own the prompt: Build your own tech writing tools using LLMs

Sat, 26 Apr 2025 13:00:00 +0000

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 running at decent speed on laptops, not even carbon footprint is a concern.

Update to my tech writing gear and tools

Mon, 14 Apr 2025 11:00:00 +0000

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 inventory and why I think they’re making me more productive.

What's wrong with AI-generated docs

Tue, 01 Apr 2025 14:00:00 +0000

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. Don’t let AI influencers studioghiblify your work as if it were a matter of processing text.

Technical writing has a depth issue

Thu, 13 Mar 2025 18:00:00 +0000

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 praxis. Nothing wrong with that, of course, except that it’s an intellectual dead end.

Technical English is nobody's mother tongue

Sat, 01 Mar 2025 16:00:00 +0000

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 language, but that doesn’t automatically turn you into a competent writer.

My time machine runs on technical writing

Mon, 10 Feb 2025 12:00:00 +0000

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.

Should you write documentation differently for LLMs?

Fri, 24 Jan 2025 08:00:00 +0000

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.

The Seven-Action Documentation model

Thu, 09 Jan 2025 10:00:00 +0000

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 turning screws. As I find the lack of deeper conversation around this topic rather unsettling, I decided to contribute some verses.

My technical writing predictions for 2025

Fri, 27 Dec 2024 20:00:00 +0000

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 my predictions for 2025, knowing I’ll enjoy being proven wrong.

The best docs are the ones we don’t remember

Sun, 15 Dec 2024 19:00:00 +0000

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 verbose documentation and even less for docs that look like they were written without care or skill. I’m not only bothered by inaccuracy, but also by bad style. In a way, as a user of documentation, I’m the worst nightmare of a technical writer.

FAQs are not the answer

Sat, 30 Nov 2024 17:00:00 +0000

Everybody loves to hate Frequently Asked Questions, or FAQs. More often than not, technical writers pale and stagger at the sight of hefty, unsorted FAQs, 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 engines. My opinion is that FAQs pose a problem only when there’s no strategy around their usage.

[Podcast] Your docs are your infrastructure

Tue, 26 Nov 2024 08:00:00 +0000

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 appearances might help. We need to be where developers are.

Why I became a Documentation Engineer (and what that even means)

Sun, 24 Nov 2024 14:00:00 +0000

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 wear many hats, but you’ll always be a technical writer. Depending on your preferences, some hats will be more comfortable than others. Docs Engineer is one of those.

How I'm using AI as a technical writer

Wed, 30 Oct 2024 08:00:00 +0000

I’ve been using large language models (LLMs) for a while now. They accelerate and improve my output at work, to the point that losing access to them would make me feel slightly impaired in some areas. Rather than fearing WriterBot, I’m embracing the additional capabilities it grants. At the same time, I’m extremely conscious of their limitations, which are abundant. Let me tell you how LLMs are helping me in my everyday work as a documentation engineer and where they’re unable to assist me.

What docs as code really means

Sun, 20 Oct 2024 09:00:00 +0000

I’ve recently started a new job as a documentation engineer. While my work is largely the same as that of a technical writer, the sound and semantics of my new job title gave me some pause and made me think about what it really means to be doing docs-as-code. To say that it’s about writing documentation using the same tools and methods as software developers is correct, but fails to acknowledge the full consequences of the fact. Most descriptions of docs-as-code are naive because they stop at the implications of being developers’ attachés.

Webinar: Contributing to Open Source Documentation Projects

Thu, 26 Sep 2024 16:00:00 +0000

Some months ago I wrote a post about open source docs contributions. My dear colleague Scott Abel (The Content Wrangler) found that to be a good topic for a webinar, so today I hosted Contributing to Open Source Documentation Projects, where I expanded my thoughts on the topic and provided some practical guidance. You can also download the slides here. Enjoy!

TypeSpec reminds us why OpenAPI exists in the first place

Mon, 02 Sep 2024 13:30:00 +0000

I’ve recently found out about TypeSpec, a new language aimed at describing web APIs, through an interview that bears the provocative title of API Design in the Post-OpenAPI Era. Leaving aside the fact that OpenAPI is very much alive, what left me stupefied was the assertion that OpenAPI files should be “automatically generated artifacts and nothing more”. After digging a bit, I found the picture to be slightly more reassuring, but still quite representative of a world that keeps steering away from human-driven design to bury itself in curly brackets paradises.

Failing (and surviving failure) as a technical writer

Sun, 18 Aug 2024 19:00:00 +0000

What does it mean to fail as a technical writer? How does one get up again? How can we correct course and rekindle the fire that helped us power through rejections, layoffs, and ostracism? Is there any switch we can toggle so that folks understand what it is that we do and provide us with the resources we need in order to contribute a verse? I’ve been thinking about all this since I became a tech writer; now I want to share some of those thoughts with you.

Discussing Markdown and structured content with Niklas Begley

Tue, 23 Jul 2024 13:00:00 +0000

Last week I had the pleasure of conversing with Niklas Begley from Doctave. It was a follow-up to The Pros and Cons of Markdown, focused on why Markdown and other lightweight markup languages could benefit from some structure, in the DITA sense, but without going the XML way. Hint: There could be a bit of JSON schemas involved.

How to set up your tech writer up for success

Sat, 06 Jul 2024 14:00:00 +0000

Congratulations! You hired your first technical writer. At some point you must have realized that you needed one, lest your product becomes a user nightmare. Or perhaps you thought that hiring a writer would free your developers from writing documentation and feel more “agile”. Whatever your motivation, you had the courage to hire a documentarian, and for that we applaud you. Now, how can you make sure your tech writer will thrive?

Contributing to open source docs as a technical writer

Mon, 24 Jun 2024 16:00:00 +0000

I’ve recently become a docs maintainer for OpenTelemetry, a pretty big open source project. As I often receive questions on how to start contributing to open source docs, this seemed the right time to write about it. Let me tell you how I started and progressed, and what you can do to start your open source documentation journey.

Review of Technical Writing for Software Developers

Sun, 09 Jun 2024 14:00:00 +0000

Just around the time I was complaining about the scarcity of books on technical writing, I got a copy of Technical Writing for Software Developers by Chris Chinchilla, a regular of the Write the Docs community. Delighted by the chance of reading a book from one of the sharpest pens in technical writing, I set aside some time to read through the nine chapters and write a review. The book taught me little I didn’t already know – Chris and I use the same tools and methods. The biggest value I extracted from TWfSD is its reflection of the times: it spurred lots of thoughts on the future of our profession and how we promote it.

Technical writing is not a dead-end job, it's a landing pad

Wed, 29 May 2024 20:00:00 +0000

With the job market getting tougher by the day, there’s a rising belief among tech writers that their role is “too niche” and a “dead-end job”. I think that’s the wrong way of looking at our profession — at any profession. Let me cast aside that dark veil of pessimism and offer an alternative viewpoint, that of tech writing as a platform to other professions, one that lets you move laterally with just a bit of curiosity and courage.

Things I remind myself when working with others

Sun, 12 May 2024 11:00:00 +0000

People usually say that I’m a pleasure to work with and that I’ve a highly collaborative spirit. The fact that I’m good at teamwork doesn’t mean that it comes naturally to me. Quite on the contrary, being a good teammate is a skill that I constantly need to train and refine. The following are things I remind myself on a daily basis, à la Dune’s inner monologues, to be a better teammate at work.

My favorite books for tech writers

Thu, 25 Apr 2024 11:00:00 +0000

Recommending books for technical writers that aren’t old technical manuals is hard. There are very few books on the craft of technical writing, a shortage that I find sharply ironic for a writers’ profession like ours. When I became a tech writer, the books that helped me the most were about other topics that make up the job, like English language, design, and the programmer’s mind. Let me share them with you.

The pros and cons of using Markdown

Wed, 27 Mar 2024 11:00:00 +0000

A few days ago I had an interesting conversation on the pros and cons of Markdown for technical documentation with Ed Marsh (Goldman Sachs) and Eric Holscher (Read the Docs) in a webinar hosted by Scott Abel (The Content Wrangler). Here are some of the things I said during the webinar, transcribed and edited for clarity.

Technical writing in 2049

Sun, 17 Mar 2024 16:00:00 +0000

A month ago, Lana Novikova asked me to imagine the future of software documentation. What will software technical writing look like in, say, 2049, when our profession will be a century old? Will we be writing markup in git repositories or use ÜberDITA in space? Will our job still exist? I’ve put my futurist hat on to picture the shape of our profession 25 years from now. Buckle up!

What to do when you're feeling AI anxiety as a tech writer

Sat, 10 Feb 2024 14:00:00 +0000

Some technical writers in my network are genuinely worried about their professional future in the AI age. Will large language models take my job, they wonder. Are we going to be replaced by GPT, they ask in meetups and community forums. My short answer is “No”. My longer answer is “No, unless you reject the benefits of LLMs”. For my complete answer, keep reading this post.

Signs that you need a technical writer

Wed, 17 Jan 2024 16:00:00 +0000

Soon after publishing Tips for hiring your first technical writer, some readers kindly suggested to follow up with a post covering the previous step in the tech writing journey, that is, the realization that one needs a technical writer. As there seems to be a strong appetite for this kind of content, I’m going to spend some words to list what I think are the most egregious signs that your team, company, or product requires a technical writer (or a tech writing team).

Docs observability, or measuring docs inside a product-docs system

Mon, 08 Jan 2024 08:00:00 +0000

As technical writers we want to know if the docs we’re writing are accomplishing their goals. In other words, we want to know how good are docs relative to the business goals they’re aiming to support or improve. Are docs serving their purpose? Which of the three budgets are docs supporting? When tech bubbles burst, roles usually seen as cost centers, such as tech writing, are ripe for layoffs, no matter how staunchly we defend them. That’s why we continue mulling over the question of value and how we measure it.

What tech writers can learn from video game manuals

Wed, 13 Dec 2023 21:00:00 +0000

I’m not only a technical writer and an avid collector of old manuals: I’m also a gamer. One of the bits I always enjoyed about video games were the manuals, from the slim booklets that accompanied arcade games to the hefty guides that helped build virtual worlds in our heads while we waited for a few kilobytes to load in memory. Those manuals still hold valuable lessons for the software documentation we write today.

Tips for hiring your first technical writer

Wed, 08 Nov 2023 10:00:00 +0000

Every once in a while, startup founders and managers decide that they need someone to create and manage their docs –perhaps after reading this letter. Some contact me to understand how they should go about hiring for a tech writer. Since I’ve already published tips for job hunting as a tech writer, I thought it would be a good idea to write down some advice for the other side, too. Here are my recommendations for software companies wanting to hire their first technical writer.

Chat with Tom Johnson about AI and tech comms

Mon, 23 Oct 2023 06:00:00 +0000

I had a cool chat with Tom Johnson (idratherbewriting.com) about AI and its impact on technical writing and documentation. Along the way, we also had the chance of discussing open source docs and the challenge of being a first-time contributor.

My favorite tech writing tools

Sun, 22 Oct 2023 07:00:00 +0000

I’ve already presented the gear I use at work. Here’s my list of favorite software tools for technical writing, the ones I couldn’t do without in my day-to-day routine. They mostly apply to a docs-as-code, software documentation setting. Notice that I’m not listing docs generators or markup languages on purpose, as we seldom get to choose them.

Bestiary: On Doc Types and Other Animals

Sat, 23 Sep 2023 16:00:00 +0000

Of documentation many are the kinds throughout the web—unnumbered, since no writer can count their multitudes, nor rightly learn the ways of their wild nature; wide they roam, these patterns, as far as Internet sets. Let me, o reader, speak of these bewitching creatures, for in the end all content types are chimeras, and those who work to reduce their number are doomed to fail…

Once Upon a Time There Were... Docs

Wed, 20 Sep 2023 05:00:00 +0000

Here are the video and abstract from my talk Once Upon a Time There Were… Docs from Write the Docs Atlantic 2023.

Tips for job hunting as a technical writer

Sat, 16 Sep 2023 09:00:00 +0000

I’ve been working as a writer in tech for more than 15 years now. During this time I’ve been at five different companies. I’ve done tons of interviews and got more than a dozen offers, some of which I ended up accepting. It didn’t always start with clicking “Apply”; it didn’t always go as expected. Whatever the outcome, though, I learned a thing or two which I’d like to share.

An experiment in humorous documentation

Mon, 17 Jul 2023 07:00:00 +0000

A few days ago I published a repository for the English Programming Language, a tongue-in-cheek parody of README files. I had a hunch and posted it on Hacker News at 3 AM. When I woke up, the repo was on the front page and already racked up 200 stars on GitHub. Not bad for a nerd joke.

But then again, why would someone write humorous technical documentation?

A tech writer's letter to software developers

Sun, 25 Jun 2023 14:00:00 +0000

Dear software developer,

You might have heard about technical writers, those mythical creatures. You might even be working with one. Whatever the case, I’d like to send you advice on how to achieve a healthy work relationship with technical writers so that you can get the best possible documentation for your product.

How did I become a technical writer

Sun, 18 Jun 2023 09:00:00 +0000

A friend asked me the other day how I became a technical writer. The question gave me pause and made me realize that, while I wrote about how to become a technical writer, I hadn’t yet written how I had become one. For all who may be interested, here’s how I got to work as a tech writer.

Docs-as-code topologies

Sun, 14 May 2023 20:00:00 +0000

Should docs stay with the code they document? Or should they rather be in a separate repo, fully managed by tech writers and docs site developers? The matter of where docs should be living when doing docs-as-code isn’t easy to untangle. With the following topologies I’ve tried to describe situations I’ve found myself into or seen in the wild. Each has its own pros and cons, though only the last is my favorite.

Episode 33 of API the Docs podcast

Thu, 13 Apr 2023 14:04:00 +0000

I’ve enjoyed doing this one a lot!

Thanks Laura Vass and API the Docs! :-)

https://apithedocs.org/podcast/love-letter-technical-writing-interview-fabrizio-ferri-benedetti-passo-uno

We need more technical writing in popular culture

Thu, 30 Mar 2023 14:00:00 +0000

Laura Vass from API the Docs asked me the other day why technical writing has such a bad rap. My answer was that technical writing’s real problem is not having a rap at all: not only is our profession relatively unknown, it almost never appears in popular culture. A solution to this would be to start featuring tech writers and documentation in all kinds of media, from TV series to movies to video games, something it’s barely happened.

High fantasy map of technical writing

Sun, 12 Mar 2023 12:00:00 +0000

Had some fun designing this technical writing map using Inkarnate. Because tech writing feels like a high fantasy quest at times.

My technical writing gear (how I work)

Sun, 29 Jan 2023 17:00:00 +0000

Technical writing requires appropriate gear to be done in a way that’s both healthy and productive. While it’s true that communicating with subject-matter experts and writing documentation can be done on a tiny Chromebook, I would compare such an experience to driving all the way from Chicago to San Francisco on a BMW Isetta: feasible, though not very comfortable nor fast, and certainly not fun for your derrière.

Hiring technical writers in a ChatGPT world

Wed, 04 Jan 2023 10:00:00 +0000

Just when we thought that we wouldn’t be replaced by WriterBot, a mounting concern is ruining many a breakfast: Bad actors could still get hired as technical writers by feeding take-home assignments to ChatGPT and presenting the resulting soliloquy as their own. Nevermind that ChatGPT content is often wrong or trite: Some think that it’d still fool hiring managers. Let me suggest two solutions to this robocalyptic scenario.

The rise of WriterBot

Sat, 03 Dec 2022 15:00:00 +0000

There’s been a lot of fuss about ChatGPT, OpenAI’s conversational bot, and its docs capabilities. Some dismissed its skills; others are thinking of selling their possessions and flee to Patagonia. Let’s do something different and entertain a hypothetical scenario where OpenAI will be prepackaged and sold as WriterBot. Let’s suppose it’ll be relatively cheap and easy to run (some deep learning software runs on desktop machines after all).

What would happen?

How to become a technical writer

Mon, 07 Nov 2022 13:00:00 +0000

Every now and then, people ask me how one can become a technical writer for software companies. Answering that question has always been difficult, as there is no clear career path for becoming a tech writer, nor a demand for tech writers such that it’d push formal tech comms education forward (at least in Europe). While the role has grown in popularity, technical writers are still a small fraction of the total workforce in the tech industry. The question is so powerful, though, that I cannot ignore it. I’ll try to provide an answer.

Learning to code as a technical writer

Sun, 30 Oct 2022 10:00:00 +0000

A recurring question from people entering the tech writing profession is “Should I learn to code?”. This query has become hugely popular in the docs-as-code age, where writers and developers live in the same DevOps trenches, eating the same CI/CD rations and publishing docs using broken tools that often lack maintainers.

My answer is “These are not the learnings you’re looking for.”

My first children’s book is about... OpenTelemetry

Fri, 14 Oct 2022 13:30:00 +0000

Almost a year ago I had this crazy idea of writing a children’s book on OpenTelemetry. In this, I was inspired not only by my lifelong love for illustrated stories, but also by the example set by Gently Down the Stream, a children’s story on Apache Kafka. I pitched the idea around a bit, processed some feedback, then got down to it. Now the book is online!

Circles of Product Truth

Mon, 19 Sep 2022 14:00:00 +0000

While thinking about unconventional technical communication, like comic books, children stories, and games, a thought occurred to me that they’re all attempts at hitting the core of what a product is and does, that is, its truth. I developed this picture of a series of concentric levels of comprehension and something resembling the circles of Dante’s Inferno came out of it. Don’t run away yet: Embrace hope all ye who enter here.

Docs Hierarchy of Priorities: A Proposal

Sun, 28 Aug 2022 11:00:00 +0000

As a psychologist, I’m quite familiar with Maslow’s hierarchy of needs. It’s an extremely popular framework for human motivation. The hierarchy, often pictured as a pyramid, states that people look for certain things following a certain order: First shelter, then food, then company, etc. As with most psychological theories, Maslow’s is almost certainly false; nonetheless, it provides a very intuitive way of thinking about priorities.

Tech Writing Skills Tree

Thu, 11 Aug 2022 22:00:00 +0000

I had lots of fun creating this D&D style skills tree for technical writers. I made this one out of the belief that there are multiple ways of becoming a tech writer, and that tech writers can specialize.

Measure it till you make it

Sat, 06 Aug 2022 14:00:00 +0000

There’s a string of questions that haunt every technical writer and documentation manager at some point in their careers: How do we know that we’ve done a good job? Have we been successful given our limited resources? How can we get better at what we do? Are the docs nailing it? How can we measure value? What do we tell upper management? More importantly, will we know what we’re saying when presenting those figures in slides? And, can you point me to the nearest emergency exit?

A love letter to technical writing

Mon, 18 Jul 2022 22:00:00 +0000

I wanted to write this post for a long time, but got to it only now, perhaps because it’s a natural segue into Let’s blog more about technical writing. Whatever the reason, I’m in a moment of my life where I feel compelled to say out loud why I love technical writing. Perhaps you’ll find some words of inspiration here. Or maybe not.

Let's blog more about technical writing

Fri, 15 Jul 2022 22:00:00 +0000

I’ve been wondering for a while why I don’t see more blogs on technical writing, tech comms, and technical documentation. I’ve been in listening mode for years, and beyond Tom Johnson’s excellent blog, it’s hard to find more content around technical writing. I’ve some hypotheses as to why that’s happening, as well as a request: We should be blogging more about technical writing and tech comms.

How to introduce prose linters at your workplace

Sun, 03 Jul 2022 22:00:00 +0000

Prose linters are great at checking documentation against style guides, either in code editors or when running a CI/CD pipeline. They can capture issues in your docs that might have been overlooked by reviewers, thus avoiding costly mistakes. The bigger problem is how to bring the value of linters to our day-to-day jobs. How do you persuade colleagues to use them when drafting docs? It takes a little patience and ingenuity.

Do it yourself: User research for technical documentation

Fri, 24 Jun 2022 22:00:00 +0000

As a technical writer, I often want to know what works and what doesn’t in the docs I’ve released. Oftentimes, I also want to know if the documentation is achieving its purpose. There’s a very good way of getting answers about the quality of your documentation, and that is user research. Analytics or feedback widgets can only get you so far.

Markdoc is not what you expected, and that's a good thing

Wed, 11 May 2022 22:00:00 +0000

Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope. It’s no wonder, then, that when Stripe announced that they open sourced their documentation format and framework, Markdoc, folks would get psyched. I, too, was startled by the sudden release. After some initial doubts, I came to love their approach.

Technical writing syllabus

Mon, 02 May 2022 22:00:00 +0000

A few months ago, I drafted a technical writing syllabus. It features all the topics that a senior technical writer should master at some point when working on software documentation.

Episode 3 of Let's Talk Docs

Wed, 02 Mar 2022 23:00:00 +0000

Episode 3 of the Let’s Talk Docs podcast is out, hosted by Portia Burton and Eric Holscher (founder of Read the Docs and Write the Docs). Enjoy!

Why I collect and read old computer manuals

Sat, 22 Jan 2022 23:00:00 +0000

It’s my ritual: every time I enter a secondhand bookshop, I go straight to the Sciences section and search for old computer manuals. They’re very hard to come by, as their owners tend to throw them away once they stop using a particular device or piece of software. Manuals also happen not to be the most engaging read for most people, which adds to their rarity; few want to peruse an old IBM AS/400 handbook while laying at the beach.

An update to my tips for working remotely

Mon, 20 Dec 2021 23:00:00 +0000

Almost two years passed since I published my tips for working remotely. Now that remote work has become almost standard in the software industry, I felt like revisiting that list to add a few items. Enjoy!

Better docs, less pain: the case for new docs-as-code standards

Mon, 01 Nov 2021 23:00:00 +0000

Despite the massive growth of docs-as-code as a documentation ethos, I continue to be surprised, year after year, by the lack of robust docs-as-code tools. Most days it feels as if docs-as-code was a giant standing on feet of clay, on the fragile toolchains that we use to create our documentation in all kinds of software companies, from startups to unicorns.

The Columbo Technique for Technical Writers

Thu, 21 Oct 2021 22:00:00 +0000

A colleague asked me the other day what’s my favourite way of extracting information from subject-matter experts (SMEs). This is a big topic in technical writing, as most of our time at work is spent chasing engineers and project managers to get bits of information.

My answer was “Be like Lieutenant Columbo”.

How to assist API design as a technical writer

Tue, 12 Oct 2021 22:00:00 +0000

The programmatic equivalent of UX Writing is API Design. The words that you use to describe your API enable conversations between software and people - it’s just a bit more structured and mechanical. That’s why technical writers are uniquely suited to assist technical teams in doing API design, especially when an API First design approach is being followed.

OpenAI and docs: AI-aided technical writing is here to stay

Fri, 27 Aug 2021 22:00:00 +0000

I get it. It’s hard to read articles about OpenAI’s coding and writing skills without feeling a shiver of neo-luddite panic running down your spine. Especially when one reads passages like the following.

Open source tools for REST API documentation

Wed, 23 Jun 2021 22:00:00 +0000

A hands-on review of the most recent open source API documentation toolchains, such as ReDoc, Widdershins, and Elements, the newest solutions from Stoplight, among others. Get the slides here.

On personality in technical writing

Sun, 20 Jun 2021 22:00:00 +0000

Had this lovely chat with Chris Ward and Tom Johnson on personality and authorship in technical documentation for the Write the Docs Podcast. Enjoy!

First steps with the Vale prose linter

Thu, 20 May 2021 22:00:00 +0000

Code linters support developers by catching errors and stylistic issues in code, such as bad formatting or keywords in the wrong places. The term comes from lint traps in dryer machines, which capture the tiny bits of fiber that separate from cloth.

Levels of embedded documentation

Wed, 03 Mar 2021 18:35:57 +0000

There was this discussion at work regarding docs in products, so I sketched a diagram to illustrate the main types of embedded docs, and their place in the product writing continuum, from UX writing to technical writing.

Working with remote teams: My Tips

Tue, 04 Feb 2020 17:36:19 +0000

I’ve been working with remote teams for years. It didn’t always work well; sometimes the reason was the content I sent, but most of the time it was the content I did not send, the missed opportunities. The tool never mattered.

Now I want to share what I’ve learned from my past mistakes. Whether you work from home, or work from an office and have colleagues working in other time zones, I hope you’ll find these tips helpful — they’ve been for me.

What is technical writing?

Wed, 09 Oct 2019 16:31:19 +0000

From time to time, people ask me about technical writing and the type of work I do. As not much is known about technical writing outside of the English-speaking world, I came up with a short answer. I hope you’ll find it useful.

About me

Wed, 09 Oct 2019 21:05:33 +0530

I’m Fabrizio Ferri Benedetti, a technical, UX, and programmer writer based in Barcelona, Spain. I write and explore tech for a living. I’ve been communicating about tech and connecting people at tech companies since 2008, first as a content strategist, then as an API designer and tech writer.

I know enough coding to be dangerous and I often create my own tools. I love the Oxford comma, em dashes, semicolons, and the interrobang. My grammar is descriptive when writing and prescriptive when editing. I break rules all the time if it helps getting a message across.