Tools for editing docs as code – By Chris Ward

Docs as code is an increasingly popular approach for tech writers that follows similar principles for writing that developers follow for writing code. Docs as code typically means writing in markup languages such as markdown, asciidoc, or restructured text. The tools for writing in these markup languages are different from the specialized technical writing tools you might have used before, and again, are often designed for coding or general writing. This post looks at some of the best you can try if considering a switch to docs as code.

Operating System text editor

Most operating systems have a text editor included by default. They are Notepad for Windows and TextEdit for macOS. They are not always optimised for writing in markup languages, but switch them into plain text mode, forgo features such as autocomplete and previews, and you have a well-integrated, simple, and unobtrusive editor that’s always available.

“Traditional” text editors

Before the modern wave of text editors were a small collection of editors that have been with us for some time. They are typically highly customizable, frequently come from a heritage of running from the command line, and can have a steep learning curve. But they have dedicated fans who swear to their efficiency and productivity boost.

These include Vim and emacs, which are both around 30 years old, but are fundamentally different in the way they operate (and of course divide people on which is ”best”). They are both cross-platform, have a well established ecosystem around them, and typically, you can run them in a terminal window, or packaged as an application for your operating system.

For macOS, the most venerable option is BBEdit. It’s “only” 20 years old and is a stalwart of the Mac platform. Its developers are working hard to compete with the new competitors such as Visual Studio Code by adding features such as a language server (this is the feature that allows many text editors to assist when writing code).

The equivalent on Windows is Notepad++. It’s open source, “only” 18 years old, and like any other good text editor, has an extensive plugin ecosystem.

New wave text editors

Primarily designed for code editing, it’s possible to extend and customize code editors such as Visual Studio Code (VSCode), Sublime, and Atom for technical writing purposes. Thanks to their coding heritage, if you are writing more developer-focussed documentation, or documentation with lots of code examples, these editors can offer a lot of support. There can be something of a learning curve and time spent configuring, but their flexibility, and open-source community around them, means you can end up with a tool set more suited to your needs.

If you are not using “standard” markdown, but another markup language such as AsciiDoc or Restructured Text, or a documentation-focussed flavor of Markdown, these editors often have plugins that support them better than other tools.

Integrated Developer Environments (IDEs)

Aimed primarily at developers, the line between the editors mentioned above and IDEs is rapidly blurring, but typically these tools offer developers a suite of tools for removing errors and inefficiencies from their code. If you are a tech writer using an IDE, you are likely also a developer or were given the tool because everyone else in a team or company uses it. While plugins are available for IDEs that make text editing more friendly, they are especially suited to any writer undertaking code or API documentation, typically offering tools to simplify and automate the process.

The “best” IDE depends on the programming language of the application you are developing. For example, if it’s written in C#, then Visual Studio (the bigger sibling of Visual Studio Code) is the tool of choice, if it’s written in Java, then probably IntelliJ.

Markdown editors

If you’re writing in Markdown, then there are a plethora of applications you can use, and the choice comes down to the features that are important to you.

If you’re looking for an option that seamlessly syncs between macOS and iOS with features such as publishing to certain platforms, grammar checking, and formatting options, then take a look at Ulysses. Other popular macOS only options are ByWord and MacDown.

If you want an online option with features for collaboration and integration with version control systems, then consider hack.md.

iA Writer and Typora are simple and writing-focussed options for all platforms (even Android with iA Writer!) including good export options to PDF and Word.

What do you use?

Tech writers write and edit text all day, and your choice of tool for the task is important and personal. I mostly use two for my technical writing (and others for fiction writing). For documentation, I use Visual Studio Code that I have customised and extended over a long period of time, I also maintain two extensions (for Pandoc and for Vale). For blog work, and especially for posts that involve minimal code examples, I use Ulysses as I often like to take my iPad and work on a post in a café or wandering around.

How about you? What tools do you use and why? Or what are you thinking of trying?