Tom MacWright

tom@macwright.com

Voice

English is a group of dialects and voices, including Standard Written English, Legal English, and the New York Blog Voice. When we write, we have a default voice and other voices we can assume. A letter to the mayor will have a different tone, vocabulary, and structure than a sext – hopefully.

Unfortunately, computing has a few special forms of English, and they’re all terrible. Here’s an anonymous example in “Machine Learning Voice”:

ANNs are processing devices (algorithms or actual hardware) that are loosely modeled after the neuronal structure of the mamalian cerebral cortex but on much smaller scales.

This description of Artificial Neural Networks should have been

ANNs are algorithms that imitate the behavior of neurons in the brain.

But the Machine Learning Voice wants to stand at the border of neurophysics, computer science, and the hypetrain, so extra words are added. These extra words are wrong - mammalian has three m’s and the inspiration for ANNs is not specific to mammals or their cortices.

Machine Learning Voice pairs its 10 cent vocabulary with the words “basic”, “simple”, and “easy”. We ban all of these words at Mapbox - they’re filler and a frustrating bummer when tasks turn out to be hard. This example is from a “A Basic Introduction To Neural Networks”, under the chapter “The Basics of Neural Networks”.

Functional Programming Voice is like Machine Learning Voice, but replaces neurophysics with math jargon and uses the word “simple” even more. Here are a few descriptions of a monad:

  • “A monad is simply a control flow construct.”
  • “A Monad is simply any type m with two functions following several algebraic laws”
  • “A monad is simply a parameterised type m, together with two functions of the following types”
  • “A Monad is simply a type that has a flatMap method, and a Functor is simply a type that has a map method.”

Of course it is.

Writing style can turn on a dime. Articles that begin with well-written framing will suddenly morph into Fancy Voice when they discuss technical topics. Technical writing needs to use jargon - you can’t explain all of programming in every article - but the structure of sentences themselves doesn’t need to become stilted every time you mention a function.

I’m not just trying to poke fun at the way coders write, and I’ve made these mistakes. The key realization is that there is no neutral voice, no truly standard form of English - there are only dialects. Almost everyone knows more than one voice and we subconsciously adjust to match real or imagined expectations.

When you’re writing for other people, make voicing a conscious process.


This is the second in a short series about writing. The first post was bracketing.

Real examples were used as illustration for this section. To protect the authors, they aren’t cited, and I want to make clear that this is not meant as personal criticism and that I have broken all of these rules myself. Like usual, I want to criticize ideas, not people.