We know that the majority of work as an engineering leader is in writing rather than coding. Yet we hardly talk about whether our words are worth reading.

With writing on the internet, there’s a natural feedback loop: if your article is low quality, you’ll struggle to get readership and engagement, and you’ll self-correct for the next article to increase those metrics. Inside a workplace and at increasing levels of seniority, that feedback loop disappears. Your colleagues and direct reports are obligated to read your emails, so it becomes easy to mistake their readership as a sign of a good job. In reality, your colleagues may never tell you something as blunt as ‘I had to read your proposal three times to understand the point’ or ‘Oh, those notes? I just marked it as read.’

Your writing directly impacts the health of your team and the execution of your product. Confusion about the vision for the team and its mission, as well as the big picture of where you want to go, are all symptoms of unclear communication. As such, we should approach the writing we send to our colleagues in the same way that we approach building products: by putting the user (the reader) first and designing a great reading experience.

Before writing

Before you start writing any email, status update, proposal, or really anything longer than a few sentences, ask yourself these questions:

• Who are you writing for?
• What are you expecting them to do after reading your writing?
• What is the one thing you want them to remember after they forget most of what you wrote?

Realistically, the level of effort you put in should be proportional to the importance of what you’re writing. The notes summarizing a weekly meeting and a document describing a three-year product vision don’t deserve the same level of scrutiny. Still, these questions are worth spending at least a minute on, no matter how insignificant you consider your current writing task.

Imagine you’re reading another team’s weekly project update email that looks like this:

Foo Team Updates (4/12/2021)

This week:

• Done: @cameron did some tracing for foo backend, notes here
• Done: @taylor and @jamie finished user interviews with the new mobile UI mocks
• In progress: @taylor is working on implementation of the new mobile UI

Next week:

• @cameron will continue work on latency improvements based on tracing work, talking to @jess
• @jamie will be on PTO all of next week
• @taylor will continue to work on the new mobile UI for foo
• @taylor will be helping our newest team member, @jackie, get oriented!

Why are we talking about foo anyway? What are you supposed to do after reading this email if you’re not on the foo team? Does Taylor not already know that Jamie’s going to be on vacation if they’ve been working together all week?

Oftentimes, this style of update happens when each individual is asked to fill in their own section for what they literally did as a way of updating their manager. They’re busy and their manager understands the project anyway, so they don’t need to say that much. Their manager, who is also busy, wants to check off their responsibility for ‘communicating project status to the org’, so they email out these notes as the team’s weekly updates. In other words, the audience started out as just the internal team, but expanded to actually be the rest of the org.

Here’s an alternative update email for the same project:

Speedy Foo Project Updates (4/12/2021)

What are we doing?

• Our team’s mission for 2021 is to increase user retention. User research shows that foo is the first place users go to in our product, so we want to make doing foo as fast and easy as possible.
• How: In Q2, we’re going to (1) improve the load time for foo on the mobile app and (2) re-design the mobile UI to make it easier to do [common task]

What do we need help on?

• Services team: @jess was assigned to review @cameron’s API call consolidation writeup. We’d love feedback from anyone else who has context on [open question in proposal]; chat with @jess to get caught up.
• Mobile team: Expect some pull requests from @taylor next week as they start coding the mobile UI (see spec here). We’re working with [mobile manager] to assign a point of contact for unblocking @taylor on [issue], let them know if you can jump in.

What’s valuable for the rest of the org to know?

• @cameron noticed some duplicate API calls to the foo backend service and did a writeup here – check it out if you want to apply the same analysis to other parts of the app
• @taylor + @jamie did user interviews (notes here). Surprising lesson: Users care the most about being able to do bar with foo and weren’t actually that confused by baz!

This email is an improvement in several areas:

• It reminds the reader why we’re doing this work
• It clearly signposts the information you’ll get out of each section
• It tells each reader what action this team expects from them
• It doesn’t assume that the reader is going to read the whole thing from start to finish and leads with the most important information
• It doesn’t include information that isn’t important in this context

Internal team updates are fine if a manager needs a way to stay up-to-date with the project, but there’s no need to fill up other teams’ inboxes with unactionable nonsense just because you ‘have to’ send out weekly updates. Other teams don’t care what you’re doing day-to-day. They care about what they can learn from your work and whether you need any action from them. Just give them what they want, signpost it for easier reading, and cut the rest.

Editing

If you’re writing something inconsequential like weekly notes, you don’t have to spend hours polishing it. Realistically, you have better things to spend time on. For the big stuff (design documents, proposals for new initiatives, product launch announcements, anything that makes you sweat), you’ll create exponentially better documents if you take care in the editing phase. To get your editorial mindset on, re-read your document (I find reading it out loud helpful) while asking yourself these questions for each section:

• Does my reader have enough background to understand what I meant?
• Is my reader going to zone out from boredom because I wrote too much?
• What would I do with this information if I were the reader?
• Is this point serving to build the main idea that I want my reader to remember, or is it distracting?

Just like with product users, you should assume your reader is busy, unmotivated to read your document, and likely to close the tab at any moment. One danger with writing at work is that we’re often too close to the details to realize what’s confusing to our readers. You have to strike a delicate balance between writing a wall of text, and not giving enough information for your document to be compelling.

If you’re not sure whether your point came through, you might want to ask a trusted colleague to read through your document and ask them what they took away as the main point. If they reach a different conclusion, your idea is unclear and needs work.

When you’re about to reach the limit of your editing energy, there’s one last question you should ask yourself:

• If you were about to email your CEO or CTO a link to your document, what would you really, truly want to say to explain it?

In spite of all your editing efforts, I bet you’ll realize there’s something you could have said better. There’s something about the fear of wasting an authority figure’s time that forces you to cut to the spirit of what you want to say. You can channel that instinct into making your writing excellent for the rest of your colleagues too.

Put readers first

At the end of the day, the stakes are relatively low if your writing at work sucks. You’re not going to get fired. Projects can succeed in spite of terrible writing if you make up for it in other areas. But you can drastically increase your chances of success with strong and clear written communication. 

Writing is the most important tool you have to unify people under a shared mission, convince others to care about what you care about, and drive a healthy, organized engineering team. By always shaping your words in terms of what you want your reader to get out of it, you’re well on your way to leading through writing.