how to write a great message

In this post, I'll show you how to compose useful messages.

Lots of people in this world are not so good at writing great messages. Emails grow into rambles, chat threads devolve into pointless arguments, and people wait until Zoom calls or in-person meetings to resolve todo items.

For engineers specifically, building the habit to write great messages can mean the difference between being a 1x vs 10x vs 100x engineer, because great messages equate to clarity of impact, better prioritization, faster debugging, increased enablement for teammates, and more. Basically: writing better messages means you have a better personal API.

At DeForm, though our team is primarily an in-office work culture, we do work in web3, an industry that is very global, digital, and technical. Clear and effective async communication often pays dividends immediately.

I use well-worded messages to ask for help, update teammates, negotiate with customers, or even just help myself with some good old fashioned rubberducking.

Let's take a look at how it's done!

1. State the goal. Clarify the reason why your message matters.

2. Share context. Predict follow-up questions that your audience may have.

3. Summarize with a call to action (CTA). Make it easy for the other person to decide.

Let's take a look at a few examples.

In this first example, Catherine is sharing some technical details with a prospective customer, and then advising them on an idea for an alternative solution and asking for feedback.

This may look like a long example to read through, but the point is not to focus on all of the content.

Pay attention to the structure of this response:

• The (1) goal is to propose a great solution and move forward on a deal fast.

• The first half of (2) context explains problems that may arise with the initial plan.

• The second portion of (2) context reveals an alternative plan with tradeoff considerations.

• The final (3) CTA is simple and clear.

The impact of Catherine's message is that we can progress a business deal more quickly, and Catherine saves at least 20 minutes of synchronous Zoom call time. Additionally, this information is "compoundable" because it can be shared across both teams in written format, and searched up easily in chat history, which reduces any overhead required for Catherine to repeat the details many times to multiple people.

Here, Kei is sparking an internal discussion with the DeForm engineering team about how to improve our notifications infrastructure for our Forms product.

This second scenario follows the exact same format, even though the content is more technical:

• The (1) goal is to solve an infrastructure scaling issue.

• The (2) context reveals the current infrastructure state, why problems may be happening, links to external resources, and a summary of the potential solutions to help move the team forward.

• The final (3) CTA is a suggestion on which solution we should pick.

The impact of this message formatting is that Kei is able to simplify a complex discussion into a clear and focused tradeoff discussion with a proposed solution. It also minimizes the amount of basic follow-up questions by including as much relevant context as possible in the upfront proposal, which means other engineers can jump deeper into clarification details or execution planning more quickly.

Here is a message I sent in order to share a lesson from exploring Typescript, TypeORM, and GraphQL configurations.

Showcasing the format once again:

• The (1) goal is to help us write cleaner code more easily.

• The background (2) context describes what is currently being done, the problem, the explorations, and the solution that solves the problem going forward.

• Finally, the (3) CTA is to follow the new process.

The impact of this message is that:

• I solidify new technical learnings by writing it down and explaining it to someone else.

• We gain documentation on a new process so that the next time a teammate encounters the issue, they won't have to go through the same amount of work to get unblocked.

• Our team sets a higher standard for our codebase that is more organized and consistent for everyone else so that we can all do better work faster.

Most of the smartest, fastest-moving, and most accomplished people I know are not only good at their craft (design, engineering, product, accounting, etc...), but are also very clear thinkers, as indicated by their ability to write great messages.

I really hope these examples and analyses can be useful for you and your team to move more quickly and get more done!

As a bonus, here's a funny meta-example that I used to get feedback on initial drafts of this blog post:

Do you have any examples of good messages that you're proud of?

Share with me in the comments! I'd love to see.

Thanks to Catherine, Kei, and Evangeline for reviews of this post!

P.S. If you want to join a team that cares about good communication and getting shit done, say hi or leave a comment below!