My favorite tech writing tools

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.

A good terminal emulator

As a docs-as-code technical writer I spend a good amount of time typing commands to either build the docs, test software, call API endpoints, and so on. The macOS terminal is painfully inadequate as a CLI, and so is Windows’s old command line. Even though they allow for a certain degree of customization, they’ve extremely limited features. In short, they bring me no joy.

For comfortable terminal sessions you want to use highly customizable terminal emulators that support tabs, split panels, and color themes. The ones I always install are iTerm2 (macOS) and Windows Terminal. Linux has a bewildering choice of terminal emulators, so it’s harder to recommend one there. I’ve found the Ubuntu default terminal to be quite adequate for most of my needs.

My Windows Terminal setup

By the way, learn common shell shortcuts. Things like autocompleting commands by hitting the Tab key or navigating commands using the arrow keys are hugely convenient. And if you feel adventurous, I strongly recommend that you customize your shell using Oh-my-zsh (macOS) and Oh-my-PoSh (Windows); you won’t regret it.

Pandoc

Pandoc is a command line tool that converts documents from one format into another. It’s immensely powerful and fast, and while the output might not be perfect at times, it can save you a huge amount of time when you’ve to convert entire sets of documentation into another markup language.

The true power of Pandoc reveals itself when used in scripts. This PowerShell script I wrote two years ago, for example, converts OpenAPI files to DocBook for use in Paligo. Another time, using Unix’s find command, I could convert hundreds of Markdown files into reStructuredText, with minimal edits, in a matter of seconds.

A good package manager

If you’re not using a Linux distribution, installing command line tools can be quite challenging. Unless, of course, you use a package manager. My favorites are Homebrew (macOS) and Chocolatey (Windows). They’ve become so prevalent that you’ll frequently find brew or chocolatey commands in installation instructions.

curl and Postman

As a technical writer for software applications and SaaS you’ll often have to document REST API operations. Instead of relying entirely on second-hand knowledge, test the endpoints yourself using curl (or cURL – nobody knows how to write it), a command line tool for executing Internet requests over a wide variety of protocols.

For a somewhat friendlier experience, and to save sample requests and share them with your colleagues, few applications beat Postman and its collection-based system. I recommend that you go a bit beyond the basics and explore concepts like variables and the generation of client code, which is quite useful for your docs.

Regular expressions

Without regular expressions I’d be a much slower technical writer. When used in scripts or code editors, regular expressions allow you to search and replace text in ways that are impossible to achieve using classic text editors. Since docs-as-code relies on text, Regex is at the center of many sweeping edits and fixes.

Unfortunately, Regex is incredibly hard to master, and I’ve yet to meet someone who is able to cook up an expression that runs on all Regex engines. That’s why I still rely on tools such as Regex101 and RegExr on a daily basis. A good Regex introduction for documentarians is Regular Expressions for Non-Programmers.

Visual Studio Code

There are many good code editors out there, but Visual Studio Code is still my first choice for editing documentation. The best feature, by far, is the version control integration, with which you can carry out git operations from the editor without having to remember complex commands. It saves so much time.

Visual Studio Code with Better Solarized Light theme

Some add-ons I always install include GitLens, which adds incredibly useful git history information to the editor, and Indent Rainbow, which makes the task of checking for indentation way easier. As for themes, there are hundreds to choose from; my favorites are Better Solarized Light at day and Gruvbox Material at night.

Vale

I’ve already written about Vale and its usefulness as a style guide checker. Wherever I go it’s part of my toolchest, together with the Vale extension for VS Code and Vale Studio, which let anyone test new rules before creating them. If your documentation has to adhere to a style guide, you should start using Vale.

A good screenshot editor

TechSmith’s Snagit is one of the few tools I happily pay for, due to the quality of its editor. I’m quite fond of animated GIFs in documentation, though, so I also rely on GiFox (macOS) and GifCam (Windows). A great screenshot tool for Windows is Greenshot. On macOS, don’t forget to check the built-in Preview’s features!

Snagit has become a bit heavy over the years, but it’s still hard to beat

Any scripting language

At some point you’ll have to automate some operation, or perform edits that would require hundreds of hours if done manually. Or perhaps you’d like to expand the features of your static-site generator with a script that scrapes content. Whatever the use case, you’ll need to learn a scripting language if you want to do all that.

My favorites are PowerShell on Windows and Python on all other platforms, as they’re pretty powerful and easy to learn. In your case, it doesn’t matter whether you use Python, PowerShell, or Bash: Try to become vaguely proficient in a scripting language of your choice. The goal, as I said elsewhere, is to become a devling.

A good virtual machine

In an ideal world, you’d work in an office that has several different machines at your disposal, each running one or two operating systems, so that you can test the software you document under different scenarios. As this is almost never the case, the best you can do is using virtual machines, which are emulated computers.

VMWare Workstation Pro 17 running my favorite operating system

I’ve been using VMWare Workstation for fifteen years now and it’s still my favorite. Free alternatives that I use from time to time include VirtualBox, Multipass, and the excellent Windows Subsystem for Linux (WSL) on Windows 10 and 11, which lets you run Linux boxes inside Windows Terminal with almost no effort.