Improving My Technical Writing2019-05-06
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.
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.
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).
Orwell’s Remedy of the Six Rules
- Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
- Break any of these rules sooner than say anything outright barbarous.
Again the passive voice is condemned.
I mean: again, a famous author condemns the passive voice.
Scott Alexander’s Nonfiction Writing Advice
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 “
unittestis an old horse and cart, whilst
pytestis 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
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:
- “just” (except for emphasis as in the tweet?)
- “only” (as in “only need to”)
- “merely” (now that can be condescending!)
simply a reiteration of Hemingway’s suggestion to eliminate superfluous words.
Go forth and write betterer,
© 2019 All rights reserved.