Writing prose like code: Dev Tool Time with Adam Gordon Bell

Adam Gordon Bell, Developer Advocate at Earthly, shares how he leverages dev tools to write consistent, high-quality technical prose.

As a developer advocate, Adam Gordon Bell writes prose as a central part of his work. As a programmer, he wants the same experience writing prose that he has writing code, where linters and build pipelines help with consistency, formatting, and error checking. When Adam joined us for Dev Tool Time on September 29, 2021, he shared his favorite dev tools for writing and how Earthly helps keep his published writing high quality.

You can watch the recording of this episode at the bottom of this blog post, but first let's check out Adam's desk setup:

Hardware

Adam drives two monitors with a 16" Macbook Pro hooked into a CalDigit Thunderbolt dock. He uses a Logitech gaming mouse, whose thumb buttons ease browser navigation.

Adam's current desk setup

Notably, Adam uses a 45lb iron weight, directly under his Macbook, as a heatsink. Impressively, his sit/stand barely notices the weight, even when it's joined by Adam's one-eyed shelter cat, Griswald.

As the host of the popular tech podcast CoRecursive, Adam uses a MixPre-6 audio interface and the popular Electro-Voice RE20 microphone, and has acoustic paneling in his office.

The cost of customization

"If you're out there and you have a crazy custom keyboard and you're using the permissive hold feature, just remember that I built that and then gave up on the whole thing."

Missing from Adam's current setup is the custom-built and programmed split keyboard he used several years ago. Building his own configuration led him to contribute code to the keyboard's software—code that people are still using today. After his keyboard broke, though, Adam discovered the unpleasantness of no longer being able to comfortably and easily use a standard keyboard, and so switched to using a regular Apple keyboard to avoid the same pain in the future.

Adam's custom keyboard and struggle

Writing as a developer

"When I started doing writing ... I want this kind of experience I was used to as a developer, where you have linting, compilers, and a build pipeline that tells you whether things work or not."

Adam's main writing environment isn't Google Docs, or even a speciality Markdown app. It's VS Code, configured with a few plugins and with easy access to a terminal to use command line utilities. Two tools are at the core of his workflow for writing Markdown, the markup language he regularly uses. markdownlint analyzes Markdown files according to configurable rules to ensure consistent and well-formed Markdown. It also can automatically fix some common errors. Vale provides grammar checking according to custom rules. While Adam uses some of his own rules, the Vale community, which includes companies like GitLab and Linode, sources a large number of rules, including those to detect "corporate speak!"

See Vale in action detecting "corporate speak

Working with these tools locally makes it easier for a single writer to avoid formatting and grammatical errors, but integrating them into a build pipeline, as Adam demonstrates, is the real mark of a durable workflow.

"If you don't use the Oxford comma, it will fail to build."

He uses Earthly, which he describes as a Makefile and Dockerfile combined together, to set up and run the build. In this instance of his company blog, Earthly runs the Jekyll build step, tests against multiple versions of Ruby, and runs the markdownlint and vale checks according to Adam's configured rules. Depending on configuration, the build really will fail if you don't use the Oxford comma.

Listen to Adam talk about two approaches to build pipelines

Used together, this set of tools lets anyone programmatically implement a style guide that anyone contributing writing to a shared blog or set of docs can follow, and provides the guarantees you want in professional writing.

Changing configurations

Customization is a running thread in Adam's setup over time. What's changed is the focus and nature of that customization. Several years ago, having a keyboard with highly configured keybindings made development more efficient. Now, with his focus on writing prose, he puts his drive to customize into a well-configured writing environment that's built to facilitate his writing workflow. Like those still using his keyboard code, we'll look forward to learning from and using whichever hardware and dev tools Adam turns his efforts toward next.

Show notes

Articles from Adam

Watch the recording

Check out the recording of the episode below, and be sure to sign up for upcoming events!