Marc's Blog

About Me

My name is Marc Brooker. I've been writing code, reading code, and living vicariously through computers for as long as I can remember. I like to build things that work. I also dabble in machining, welding, cooking and skiing.

I'm currently an engineer at Amazon Web Services (AWS) in Seattle, where I work on databases, serverless, and serverless databases. Before that, I worked on EC2 and EBS.
All opinions are my own.


My Publications and Videos
@marcbrooker on Mastodon @MarcJBrooker on Twitter

Writing For Somebody

Who's there?

Sometimes I write long emails to people at work. Sometimes those emails are generally interesting, and not work-specific at all. Sometimes I share those emails here on my blog. This may be one of those times.

Always write for somebody.

Always have an idea in your head, as you’re writing, who your writing is intended to communicate with. Sometimes, that’s a particular person. Your boss. A mentee, or mentor. Bob from legal. Sometimes it’s a group of people, or a kind of person. Sometimes its your future self, or past self1.

I find that having a particular audience in mind allows me to focus my writing better, to communicate better, and make myself more likely to achieve my writing goals. To have empathy for them as a reader, as I would have empathy for somebody I was trying to communicate with face-to-face.

It’s hard, and perhaps impossible, to distill empathy into a structured approach. But thinking about a particular audience does make for a somewhat useful, if incomplete, checklist:

Answering each of these questions provides me with a clear lens through which to evaluate whether my writing is going to be successful.

What do they already know? and What misconceptions do they have? help focus the use of space and time in a document. Where to spend detail and explanation to ensure clarity, and where information can be elided for brevity. They also help ensure information is presented in the right order, and repeated the right number of times.

What do I want them to know or understand? helps make sure the right information is present in the document. If there is something that’s not covered by What do they already know? but I do want them to know at the end, then I need to ensure that information is in the document.

What do I want them to do with this knowledge or understanding? is the call to action. Sometimes, like with a lot of the writing I do at work, that call to action is explicit. I want somebody to make this decision. Or move in this direction. Or make this investment. Sometimes, like with this blog and academic papers2 the call to action is more subtle. I want people to understand things, and perhaps to use them in their future work.

What do they want to get out of the time they’re spending reading my writing? is the quid pro quo. The value for the reader. In some cases, the value is explicit. In others, you’re asking for somebody’s time and attention (deep reading takes significant time and attention) in order to ask them a favor. Is my writing respectful of their time? Or am I wasting their time while asking for more of their time? That doesn’t seem like an experience people would be keen to repeat.

The odd one out is What are they afraid of? It’s emotional, and personal, and not about rational decision making at all. That’s the point. Humans aren’t purely rational decision makers. We approach each decision with a lot of context, a lot of prior experience, and sometimes with our own scars and blind spots. Frequently, I see folks who are unable to drive a particular decision because they haven’t been explicit enough about the readers’ prior experiences. Last time we tried this, the bread got stale before we could buy the cheese. Are you thinking about the cheese far enough ahead this time?

This doesn’t capture everything important about writing, of course. But nearly every piece of ineffective writing I see doesn’t have a clear answer to one or more of these questions.


  1. Tonally, I think of this blog as being addressed to my past self as an audience. He’s somebody I know rather well.
  2. I read a lot of research papers. Reliably, the ones I enjoy the least are the ones that were written for the peer reviewers, with the primary call to action being accept this paper into your conference. This misalignment of incentives between writers and reviewers and consumers of research, a kind of principal-agent problem, is a serious downside to research peer review.