Write like you code

Good writing is like good code, it's simple, efficient, and structured. Conversely, bad writing resembles bad code. It's unnecessarily complex, inefficient with the reader's memory, and structured like a bowl of spaghetti.

Good writing is simple

As a drunken Developer once said: "Good code is code that can be understood by a junior engineer. Great code can be understood by a first-year CS freshman. The best code is no code at all." Writing is similar. You should strive to use the simplest words that get the point across. Novice writers use big words to hide their own lack of understanding, similar to how novice programmers use frameworks. You don't need React for your landing page, and you don't need to use the word "sesquipdealian" to describe something long. Strive to make your writing as fluff-free as possible. If something in your writing doesn't need to be said, don't say it. This is the writer's equivalent of "the best code is no code at all".

Good writing is efficient

Similar to how a programmer must bear in mind the finite resources of the computer, a writer must consider the mental resources of the reader. Attention span and memory are the writer's equivalent of CPU Cycles and RAM. Humans get bored quickly and bad writing accelerates that boredom. Just as an exponential function takes too long to execute, bad writing takes too long to get to the point. Good writing combats the reader's boredom with frequent humour or insight. One of my favorite mechanisms for keeping the reader engaged is to ensure they have an epiphany every 250 words. David Perell calls this the "Raymond Chandler rule".

Humans, like computers, have a limited amount of working memory. Most people can hold between 5 and 9 items in their mind at any given time. However, anything that occupies our working memory also reduces our capacity to think. Good writing acknowledges the limits of our short-term memory. It flows naturally from one idea to the next, minimizing the chunks of information we have to hold in our minds at any given time.

Good writing is structured

Poorly architected code contains giant functions and God Objects that do too much. This is the writer's equivalent of run-on sentences and having one big paragraph. Your writing, like your code, should be structured in a way that maximizes understanding for the reader. A paragraph that talks about the similarities between structured code and structured writing shouldn't talk about the similarities between code review and proofreading. A module for sorting shouldn't contain functions for sending network requests. Follow the single-responsibility principle with your writing. Each sentence should contribute to the main idea of its containing paragraph, and each paragraph should contribute to the overarching idea of the piece.

← Back to home