Improving My Technical Writing

Documentarian

Mikey showed us the Write the Docs definition of a documentarian:

A documentarian is someone who cares about documentation and communication in the software industry, regardless of job title.

I identify with this. While I love to write code, I’ve come to realize without correct communication it’s useless.

Hemingway App

Mikey also recommended this and I’ve used it on every blog post since. It’s a style highlighter that marks complicated or unnecessary language. You can then remove it to better imitate famous adventurer-author Ernest Hemingway. (He also pioneered the standing desk.)

Hemingway had a “Keep It Super Simple” (KISS) approach. There are a lot of articles about this, for example the guidelines he recommended from the Kansas City Star:

• “Use short sentences.”
• “Use short first paragraphs.”
• “Use vigorous English.”
• “Avoid the use of adjectives.”
• “Eliminate every superfluous word.”

Hemingway app calls you out on complex sentences, adverbs, and the passive voice. Paste in your text and look at the colour-coded highlights:

I’ve started running my blog post drafts through it. I find the passive voice common in technical writing, even my own. It’s the biggest thing I work on removing with Hemingway (app).

Find it at hemingwayapp.com, in browser or on desktop. The help page is also a worthwhile read.

Orwell’s Remedy of the Six Rules

Similar to the Kansas City Star’s rules, author George Orwell defined his own Remedy of the Six Rules:

1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it out.
4. Never use the passive where you can use the active.
5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.

Again the passive voice is condemned.

Woops!

I mean: again, a famous author condemns the passive voice.

Scott Alexander’s Nonfiction Writing Advice

Scott Alexander is the prolific blogger behind Slate Star Codex. His Nonfiction Writing Advice post is typically extensive.

Some things I’ve tried to apply from this essay:

• Adding more (micro) humour to my posts. For example in my algorithmics post I wrote “unittest is an old horse and cart, while pytest is the batmobile”. This was funny enough for the official pytest twitter to quote it!
• Telling you to do things. Before, I wrote phrases in the academic “We add this code:”, or the selfish “I added this code:”, or the longwinded “The code author could then become the one who proceeds to add this code:”. Now I write “Add this code:”. Directing instructions at you, the reader, is shorter and more engaging. Even if your text editor isn’t open, you can imagine adding the code!
• Adding more section headers. A lot of blog posts are hard to navigate. Adding more section headers remedies this. I don’t like abstract numerical headings like Scott. I prefer to label each section to help skimming.
• Breaking up the flow with mid-post images. Like below.

John McPhee’s Draft No. 4

John McPhee is a fantastic nonfiction author whose informative prose flows like poetry. I read his book Oranges a couple years ago and it stuck with me. I’ve eaten a lot more oranges since.

He teaches you with such descriptive passages as:

In Florida, most orange trees have lemon roots. In California, nearly all lemon trees are grown on orange roots. Plums can be grown on cherry trees and apricots on peach trees, but a one-to-one relationship like that is only the beginning with citrus. A single citrus tree can be turned into a carnival, with lemons, limes, grapefruit, tangerines, kumquats, and oranges all ripening on its branches at the same time.

I was thrilled to learn through a [Twitter thread on improving writing by @DRMacIver](https://twitter.com/DRMacIver/status/1118575686833332224) that McPhee wrote a piece about his writing process, Draft No. 4. It contains a variety of advice delivered in his unique style. I won’t do it any justice by quoting or summarizing it, so find the time to read it.

McPhee is an entertainer first, and an informer second. A technical document in his non-linear, florid style would be fun but referencing it would be slightly impossible. Don’t emulate his writing 100%, unless you’re also chasing a Pulitzer prize.

Simply Remove “Simply”

This tip comes from Chris Coyier’s Twitter:

The #1 word I delete in tech article drafts is “simply”.

I do think that word is a bit exclusionary in that it’s very possibly someone reading doesn’t find the task simple at all.

But more so, it just isn’t needed in the sentence. It reads better without it.

There are other words and phrases in this category:

• “just” (except for emphasis as in the tweet?)
• “only” (as in “only need to”)
• “merely” (now that can be condescending!)

This is simply a reiteration of Hemingway’s suggestion to eliminate superfluous words.

Fin

Go forth and write betterer,

—Adam