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. Each has its own pros and cons, though only the last is my favorite.

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 all kinds of media, from TV series to movies to video games, something it’s barely happened.

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 very comfortable nor fast, and certainly not fun for your derrière.

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.

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?

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.

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