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 extremeley conscious of their...
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...
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...
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...
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...
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.
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...
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.
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...
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...
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...
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...
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.
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...
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...
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...
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...
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...
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...
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.
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.
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...
Here are the video and abstract from my talk Once Upon a Time There Were… Docs from Write the Docs Atlantic 2023.
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...
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...
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.
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.
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....
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
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...
Had some fun designing this technical writing map using Inkarnate. Because tech writing feels like a high fantasy quest at times.
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...
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...
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...
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...
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...
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...
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...
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...
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.
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...
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.
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...
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...
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.
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...
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 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!
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...
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!
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...
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”.
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...
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.
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.
Had this lovely chat with Chris Ward and Tom Johnson on personality and authorship in technical documentation for the Write the Docs Podcast. Enjoy!
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.
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.
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...
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.
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 tech journalist and content strategist, then as an API designer and tech writer. I know enough coding to be...