Adam Johnson

Home | Blog | Projects | Colophon

Improving My Technical Writing

2019-05-06

Despairing author seeks writing advice

I found Mikey Ariel’s talk on documentation at DjangoCon Europe 2019 “Docs or It Didn’t Happen” well timed. I’ve recently been focussing on the lifelong skill of writing, in particular for technical writing such as this blog.

I want to make my writing straightforward whilst entertaining. In technology, it’s important to use clear, simple English since it’s a second language for so many of us. Misunderstandings mean bugs!

The talk was one more jewel among several other resources I’ve looked at recently. Go watch it, and check out these resources, some of which Mikey mentioned.

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. Whilst 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:

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

hemingwayapp.com with blog sample

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:

Fiddlecrabs

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 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 moreso, it just isn’t needed in the sentence. It reads better without it.

There are other words and phrases in this category:

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

Fin

Go forth and write betterer,

—Adam


If you found this useful, I'd be grateful if you subscribe to my future posts, via RSS, Twitter, or email:

Tags: django