#49: How to Write Effectively at Work

Hey friend,

I know I promised you that I would write about building habits in this Mektup. However, I was traveling for business and couldn't find the time and energy to gather my thoughts. Also, I wanted to save it for the 50th Mektup. It will be a good chance to talk about building habits at the 50th mark.

Meanwhile, I want to share something else with you.

With the extensive usage of tools like Slack, Confluence, and Google Docs, we—especially leaders—struggle to be articulate. In school, we were all taught to start writing by forming bullet lists, building our arguments, adding more background, and finishing our text by summarizing everything. Although this strategy worked until the end of education, it doesn’t work anymore, especially in the work context. People often don't read our messages well, or they skim texts loosely and hastily. People often miss the value of our messages—what's important to them.

We sometimes spend a long time crafting a message and become wordsmiths of the sentences and words to make our message more impactful. Once we send the message, we feel proud because an announcement message often records the conclusion of our diligent hard work. However, talking to the people after our announcement reveals that people were not hooked on our idea. We then spend hours and hours explaining our idea in meetings and conversations.

How can we shorten the time we put in after that announcement? More than hooking people to our idea, we need to be concise in text and make clear what’s valuable in our text to the reader.

As what we learned in education no longer works, we must relearn how to craft a message.

Recently, I watched this video by Larry McEnerney, Director of the University of Chicago's Writing Program about writing effectively. Although it’s aimed at academic writing, there are fantastic insights we can all benefit from and apply in our Slack messages, Google Docs, pull request reviews, presentations, and what have you.

Our text is not about us

It's about readers.

That is the biggest mindset switch McEnerney talks about. We're using our writing to think about our world while people are reading our stuff to learn what's valuable to them in our world. They read our stuff not because it's valuable to us but valuable to them.

That's why we must focus on what value we bring to the reader. We might have the most novel idea that nobody thought of. But if that idea doesn't bring any value to anyone, then nobody will care.

Writing is about changing the reader's ideas. What we think is unimportant if our thoughts don't change something in the reader's mind.

But how do we bring that value? How do we change the reader's mind?

Bringing out the problem

A value comes from an existence of a problem. We either surface a problem that the reader wasn't aware of or solve the problem that the reader already had.

And two characteristics define a problem: Instability and cost/benefit.

Instability in a situation causes the problem. For a problem to exist, there has to be an imbalance. We need to show readers that instability. As leaders, we often try to solve that instability by hiding them in our messages. However, to define a problem, we need to create that instability in our text and make it visible. Words such as but, however, although,  and nonetheless create contradictions. These words help to point out what is challenging or conflicting in any situation. While defining a situation and working towards building the problem, these words help to point out the exact issue.

For example, look at how I used the word "however" in the above paragraph.

Once we make the instability visible, we need to explain what is the cost of that instability and what will be the benefit of getting rid of that instability. That's the main value to the reader. This cost and benefits component is what arouses interest and keeps the reader engaged. If the words don’t benefit the reader, nobody will care about the writing. They have no reason to keep reading.

While explaining cost/benefit, we also need to define who exactly will benefit from solving the contradiction we introduce or who will deal with the cost of that instability. We need to make the audience prominent. Readers have to understand who the text is written for. For example, at the beginning of the text, I narrowed down the audience of this text to leaders.

Now that we learned the components of effective writing, let's look at a few strategies to apply our learning at work.

How to apply it in daily work

  • When writing a Slack message in a team channel, think about whom your message impacts. If you're writing in your team's Slack channel, your audience is already defined. But still make the cost/benefit to these people clear and visible. If you're writing in a wider-audience channel, make clear who your message is for.
  • When writing a Pull Request description, Request for Comments Document (RFC), or Architecture Decision Record (ARD), don't write your ideas just from your perspective. Somebody will read your writing, so the text is for them.
  • If you're unsure about how to write for other people, just write whatever comes to your mind but ruthlessly edit what you wrote later on. Convert your narrative and change your angle from yourself to the reader.
  • Build a background of the problem. Use words that create a contradiction (but, although, however, nonetheless, etc.). If you need to convince people to change course, create that tension and instability.
  • If you don't know how to create that tension, look at a few well-written texts and search for words such as but, however, although, nonetheless, etc.
  • Make cost and/or benefit visible. Show what they will miss out on or what problems they will have to deal with in the future if they don't follow your ideas.

That's it. See you next time at the 50th Mektup!

— Candost

P.S. I'm taking a break from social media (Twitter, Linkedin, HN, Mastodon, etc.) until April 1st. I believe it distracts me a lot, and I want to test how my life will be without it. I will share my reflections once I'm done.

What I Published Over The Last Two Weeks

The Challenges of Distributed Systems

While we talk a lot about how distributed systems and databases work, we also need to understand the problems, faults, and failure scenarios we will face.

Understanding all the trouble closes the loop in our knowledge and helps us build "better" systems.

The Challenges of Distributed Systems
The most common and known problems and challenges of Distributed Systems.

Shift Left on Security

Shift Left on Security from Accelerate book is one of the 24 capabilities that drive improvements in software delivery performance.

Can we explain the "Shift Left on Security" to a five-year-old? If so, how?

Shift Left on Security
How would you explain the “Shift Left on Security” to a five-year-old?
Newsletter Last Updated: Jan 26, 2023