Writing at work

In yesterday’s article, I credited writing skills, not technical prowess, for having the most impact on my career. Many white-collar jobs revolve around persuading others and explaining our ideas — and I’ve seen countless design proposals, promo packets, and escalation docs tanked by turgid prose.

Back in 2021, I penned a Twitter thread with a handful of writing tips, but Twitter is a poor medium for long-term text. It might be time to recap the advice in a format that’s easier to digest — and hopefully less riddled with typos, too.

My general advice to techie writers boils down to four points:

1. Recognize that the voice in your head is an unreliable narrator. When you’re reading your prose right after writing it down, you’re hearing what you wanted to say, not what the text actually spells out. It helps to add a bit of time between writing, proofreading, and hitting “send”. Another handy trick is to find an empty room and read the text out loud.

2. Come up with a crisp tagline for what you’re about to write. Hone in on one or two key points you need to get across. Test every sentence in your doc by asking if it helps that narrative — and if not, get rid of it or rephrase.

3. Write for your audience, not for yourself. Make it clear what’s at stake and anticipate major questions. In most cases, the audience doesn’t want to learn your craft, so find a way to explain concepts without pages of trivia or dozens of Wikipedia links.

4. Keep in mind that when you’re competing for attention, simple sentences and short words beat flowery language. The Economist Style Guide and The Chicago Manual of Style are accessible and worth your time.

For escalations and disputes, you should also make sure you're addressing the right problem and putting forward the right choices. Identify on the most tractable causes and the most productive solutions. For example, if a team is not prioritizing your requests, “make them do it” is worth less than “here’s the list of their priorities; we either need to delay X or hire an extra person to get it all done.”

If you’re trying to settle an argument, it’s equally important to agree on the underlying facts. Disputes where the parties present vastly divergent accounts of reality are at best a waste of time — and at worst, a signal of deep dysfunction on both sides.

For any longer-form text, it pays to have an editorial process in place. We have an intense attachment to what we write, and it’s often harder to delete a paragraph to add a new one. Here’s how I tackle this:

1. I start with a collection of hastily-scribbled mnemonics that capture the intended flow of the article. I spend some time moving, deleting, or rephrasing this word soup until the structure of the document feels right.

2. With the labels in place, I begin fleshing out the associated paragraphs. I get the words in, but I’m still expecting to do an angry rewrite down the line.

3. I put myself in the reader’s shoes. I pick a specific persona and try to figure out what they already know, what they’re hoping to learn, and what’s irrelevant in their walk of life. I keep making edits until my inner reader is content.

4. I wrap things up with a final wordsmithing pass. At this point, I’m not making structural changes; I’m just getting the phrasing right.