On Writing Well: Through a TDD Lens

Photo by James Harrison on Unsplash

I would much rather write code for a new application than write a blog post… at least until I started thinking about writing in a different way.

I’ve never been a phenomenal writer. I would procrastinate writing every essay in college and allow the smallest writing task to daunt me. To this day I painstakingly review emails before pressing send. While I’ve focused on improving my code writing skills, I’ve kept my literary writing skills in a dark corner.

Turns out, I’m not the only engineer in this boat.

When I discussed my desire to improve my writing skills with my manager, he suggested that I read by William Zinsser. Not too far into the book, I noticed similarities to Test Driven Development (TDD) and a light bulb went off. Applying TDD — a framework I love — to writing might actually make writing more approachable.

This blog post is my first try at testing the thesis and so far it has proven to be valid. I distilled the similarities between TDD and On Writing Well, and I look forward to equipping you with a new way to think about writing.

What is TDD?

TDD is a tried and true practice to improve the quality of one’s code. There are three underlying steps, which are referred to as the red, green, refactor cycle.

  1. Red: Before I write any functional code, I write a test to describe the expected behavior of that unwritten code. This test will fail (become red) because I haven’t written the code yet.
  2. Green: I then write the smallest amount of code to make the test pass (turn green).
  3. Refactor: I finally look for ways to improve the code and simplify it.

Let’s walk through each of the steps to understand how they relate to writing.

Red

When writing a test, I ask myself a few questions such as or These answers help me break down the new functionality into manageable pieces and form my approach of what to focus on first.

emphasizes that “[u]nity is the anchor of good writing.” (pg. 50) Unity is achieved by answering a set of questions before we start writing, such as or and keeping these goals in mind while writing.

In both forms of writing, we have to start with a plan. An anti-goal at this stage, though, is planning too much. In the same way that I wouldn’t expect the first test to be filled with every assertion, I wouldn’t expect my writing plan to lay out every single paragraph of my first draft. Without a simple guiding light — or failing test — it’s hard to focus on our objectives while writing the implementation.

Green

TDD encourages this implementation to be the simplest amount of code we can use to get the test to pass.

Zinnser wants writers to “constantly ask: what am I trying to say?” (pg. 9) to ensure we are writing in a clear and simple manner. Once we achieve the objective, there’s no obligation to keep writing or add fluff since “Clutter is the disease of American writing.” (pg. 6)

In coding and writing at this stage, we want to use the fewest number of words to achieve our objective. When the first draft is done and the test passes, then we get to have some fun to make the implementation even better.

Refactor

This is where I get to be creative with the code. I simplify the code into its cleanest, most readable form. For instance, in some languages instead of using a “for” loop, I could utilize a map to loop over objects instead. The change could be as big as renaming a variable for readability or breaking a piece off a monolith into its own service.

encourages us to spend the majority of our time in this stage. “The secret of good writing is to strip every sentence to its cleanest components.” (pg. 6) Zinsser even goes so far to claim that “[m]ost first drafts can be cut by 50 percent without losing any information or losing the author’s voice.” (pg. 16)

In both scenarios, our goal is to refactor down to the basics, but with style. We want to keep the reader engaged and provide readability for future coders.

Bonus Round: Pairing

https://tanzu.vmware.com/content/blog/what-s-the-best-way-to-pair

Pair programming is another Extreme Programming (XP) practice, just like TDD. If two developers are pair programming, that means they are collaborating together to write code on one machine. Not only does this practice help the developers learn from each other, but it also helps solidify what they learned by teaching. The pair is also an extra set of eyes to spot issues that the person with their hands on the keyboard might not have noticed.

Zinsser ends by discussing editors. “What a good editor brings to a piece of writing is an objective eye that the writer has long since lost.” (pg. 299) Good editors are collaborative, generous, and always have your back. They’ll get you out of your head by helping decide between routes to take.

A good editor and good coding pair both work with their partner to help prune objectively, while crafting the best piece of writing / coding possible.

Conclusion

Don’t get me wrong — there are plenty of differences between coding and writing. But just like many topics, sometimes finding similarities is all it takes to make a topic more approachable. I hope this encourages other developers to try writing again. And maybe this post will help non-coders see how relatable writing can be to coding.

My copy of On Writing Well overlaid on my favorite IDE — IntelliJ

Software Engineer @VMware Tanzu Labs. Dog Mom. Goldfish connoisseur.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store