Refactor Your Writing

“Write your first draft with your heart. Re-write with your head.” — Anonymous

In other words, the first draft is almost always too long and poorly structured. To be clear and concise requires at least a second draft, and often more. Or put more succinctly: “The first draft of anything is shit.” — Ernest Hemingway

We programmers refactor our code, by changing its structure while retaining behavior, so that code remains readable to others now and latter. The same can be done for writing – emails, messages, blog posts and such. Refactor your writing before hitting “send”, 1 much like programmers refactor their code before committing or merging it.

A common problem with communication is unwritten assumptions. Naturally, not everything in our mind gets translated to text. This leads to a sort of void in the reader’s mind, which – given the propensity of the human mind – leads to “filling in” with assumptions of their own. Another problem is unnecessary complexity in structure of sentences, which complexity might get in the way of comprehending the original message. 2

All off these issues can be addressed by doing a Refactor postmortem not on code but on what was just written. It could be an email, a GitHub PR review comment, a moderately sized Slack message or whatever that is intended to be read by others. The mechanism is same – you re-read the message after “version 1”, and address the potential pitfalls mentioned above. Imagine someone different, that is not privy to your thought process, is reading it with limited time and energy - would your message be effectively communicated to them?

Footnotes
1.
When this idea originally occurred to me along with the succinct mnemonic “refactor your writing”, naturally I Google’ed it … and then arrived at this post from 2012 where its author Adarsh had the same idea.
2.
Another pitfall comes from the role affect (mood or feeling) plays, but that’s a topic for another day.
#blog