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.

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.

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.

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 their number are doomed to fail…

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 or two which I’d like to share.

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?

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.