published 2024 January

Like a programming language, English's purpose is to taxi ideas. As well, there are many ways to do the same job, some more effective than others.

But unlike code, English presents two roads that ideas can drive down: the spoken word and the written word. They lead the same place, but one is a windy one-lane dirt road full of intersections and backtracking. The other is a coastal highway.

When we write, we pave the highway. We put in an enormous amount of effort up front to benefit people we don't even know will come. If we instead write as if we are speaking, the highway is quickly eroded by waters of disinterest.

Here's how to pave a highway.

Leave Something Out

Laura Shapiro shares an anecdote in Something from the Oven that box cake mixesthe ones where you just add eggs and waterat one point embedded the eggs directly in the mix, dehydrated to be as shelf-stable as the rest. Consumers merely added water, but sales were low.

Psychologist Ernest Dichter suggested leaving out the dehydrated eggs and directing the consumer to add their own. Consumers felt more engaged, and sales skyrocketed.

Let the reader add their own eggs.

Writing is Code Golf

Code golf1 can be fun, but it is infamous for yielding unmaintainable real-world code. Squishing as much information as possible into as few characters as possible inevitably sacrifices reader understanding.

The better code golf would be to optimize for reader time, not character count. That is, measure density as:

\[\dfrac{meaning\,gleaned}{time\ spent\ reading}\]

In writing, this kind of density means everything. There is no compiler, scaling, or even syntax to worry about. There is only the reader. They float in orbit, moving from piece to piece until they spot something interesting to land on. Clear words are like electromagnets that pull them in.

Be Nontechnical

Technical ideas can be expressed nontechnically a lot more often than you may realize. It is a matter of time and effort.

What is a static website generator? Take ten seconds to describe it in your head before continuing.

Here is mine:

A static website generator turns documents into websites.

What is Markdown? Again, try it yourself.


Markdown is an agreement on how to indicate rich text in plain text.

Your descriptions were probably more precise. Maybe you meandered a little and used some technical terms. The result of those actions is slightly more meaning, but it's a lot less understandable to laypeople.

Usually the trade is not worth it. Readers not in your mindset will be exhausted easily. Spend the effort to be at least one step less technical than is your instinct.

Use Imagery

Recall the seeds planted in you by your grade school training on imagery. It’s difficult to nurture the habit, but even a little thought can bloom beautiful prose.

Instill Understanding, not Correctness

\(E=mc²\) is technically wrong. The actual equation for energy is

\[E=\sqrt{m²c^4 + p^2c^2}\]

where \(p\) is momentum. \(E=mc²\) is a simplification that works well enough for human-scale speeds. But it is still taught in classrooms, all the way until reaching the point where it breaks downwhich most disciplines never reach. It is easier to teach that way.

Mold your concepts to be taught easily. Do not fret about being correct at the edges. Do not even mention the edges. They are a distraction from the teaching.

Prefer Understanding over Grammar

A grammar exists to make communication easier. But the English grammar was not constructed; it grew and grows organically. Patterns in sentence structure existed before anyone wrote them down, and new developments aren't decided by some council of elders. They're decided by popular use.

The English grammar is a description, not a prescription. Grammars and dictionaries are continually updated to match current usage, not the other way around.2

Aim to be understood. Don't let any rule get in the way.

Use Staging

Like code, the worst person to test what you've written is you. Find a friend who enjoys reviewing your work constructively, or stash the piece in some staging area and look at it in a month with fresh eyes.

You'll learn what works and what makes you bored of reading.

Give Yourself a Break

After all this, it's better to publish something 90% done than to toil away trying to reach 100% forever. Give yourself some slack and hit the button.

  1. Code golf is a form of entertainment where programmers try to solve a programming prompt in as little code as possible, however unreadable or unmaintainable the result may be.
  2. As an example of the bleeding edge between popular use and description: According to all major dictionaries, songs must have lyrics. If you go by that, the Mario theme is not a song. Much of the EDM genre is not songs.