Message Crafting for software engineers

Douglas Gresham
19 min readNov 16, 2021


A person holding up a sign saying “Do not wait for leaders, become them”
Photo by rob walsh on Unsplash

One of the key insights for staff/principal engineers is that the job is at least as much about people as it is about tech, increasingly so the more you grow your career. You have stakeholders to manage, junior engineers to mentor, peers to butt heads with, and so on.

Most of us trained our whole lives to do the technical part, and the people part sneaks up on us. Managers (hopefully!) get some training as they take on reports, but for individual contributors it can be a case of self-directed learning in the best case / “just figure it out” in the worst case.

In my current role, I’ve put together a series of leadership skills workshops geared towards ICs. I have great source material for some topics (Elements of Influence/Elements of Power for influencing, Crucial Conversations for hard feedback conversations, Frameshift Consulting’s excellent Ally Skills workshop) — but one topic I haven’t found a good unified resource on was Message Crafting. I wrote my own, and this post has the content I use. I run this as a two hour workshop, with a 30 minute exercise at the end where groups of 3–4 come up with a message for a given scenario (there’s an example of this at the end).

I’ve scattered links throughout to backing studies and articles, but the best single piece I’ve read on the topic is from Smashing Magazine, “Effective Message Framing to Motivate Users”. You’ll see its influence throughout.

Stories and your brain

A model of the human brain
Photo by Robina Weermeijer on Unsplash

With apologies to anyone who knows any neuroscience for the gross oversimplification I’m about to indulge in, I’ll start by talking a little about the brain — specifically, the amygdala.

An anatomical diagram of the human brain showing the position of the amygdala
Anatomy of the Human Body (Henry Gray 1918), Public Domain.

The amygdala has a primary role in processing memory, decision making and emotional response — and the key point is the colocation of these functions, as opposed to language, higher order reasoning, conflict resolution and so on which are in the realm of the pre-frontal cortex. This has two main consequences:

Decision making is driven primarily by emotion. A consumer’s emotional response to a TV ad influences intent to buy more than the content by a factor of 3-to-1. You can see this effect directly by putting someone in an fMRI scanner and asking them to evaluate brands — it’s the neurons in the amygdala and other parts of the brain associated with emotional response which light up (more here).

People have better recall of emotion than facts. Studies show that our most vivid memories are of emotional events, that emotional items are more likely to be processed when attention is limited, and that we remember most clearly what we had an emotional response to in a situation than the other details of it (more here).

Photo by Nong Vang on Unsplash

In addition to how emotion and memory interact, there are a couple of fun ways in which the way our brains work impact how we craft messages — again, directly measurable by fMRI.

First, we don’t have to experience an event directly in order to fire the same emotions as if it was. If I say the word “lavender”, the limbic brain (where the amygdala is)— in addition to the parts of the brain that handle smell input — are activated. Even more weirdly, this still holds for metaphor and simile — if I say someone has a nice singing voice that’s processed primarily in the neocortex because it’s quite dry language, but if I say they have a voice like velvet the parts of the brain that deal with touch sensations fire up!

Second, where we can understand the narrative behind something, more of the neurons responsible for feeling emotion light up. You can measure this with something as simple as watching someone lift a glass and intending to drink from it, versus someone lifting a glass with no follow-up action. Perhaps most importantly, if you don’t provide the narrative, people will fill it in from prior experience and memory — which can work against you.

All of this means: in crafting a message, we must tell a story which makes people feel what we want them to feel to have the best chance of landing our message successfully.

Setting goals

A soccer goalpost
Photo by Qurratul Ayin Sadia on Unsplash

Others have written far better than I can about the benefits of goal setting; as it pertains to message crafting, I strongly advise actually writing down your goal before you start trying to figure out anything else. Intentionally referring back to that will help you with a lot of what I’m going to be talking about, and keep you from muddling your message with irrelevant details or veering off into paying off your own emotional needs.

You’ll be amazed how much better everything goes if you commit a goal to paper before starting .

Understanding your audience

A speaker addressing an audience
Photo by Miguel Henriques on Unsplash

After you write down your goal, the next step is to understand your audience. If your answer is “my audience is everyone”, you’re setting yourself up to fail. Try to come up with a persona — ideally, anchor on a person or people you know, and use their names to help you see them less abstractly.

What are their expectations? What will they be wanting to get out of you, and what preconceptions will they approach your message with?

What’s the size of your audience? For larger audiences you’re likely to want messaging that is concise, visual and shareable; if your audience is small, it’s likely to be more conversational and need more space for their input.

What is their level of familiarity with your subject? This will impact how simple you need to make your language and whether you use any jargon (we’ll revisit jargon a little later).

Write these things down! It’s easy to think you’ve considered all of these things, but the act of committing to paper (real or virtual) will show you whether you really have.

Finally, ask for feedback afterwards. Talk to people about how your message landed. Run surveys. Follow up. Learn for next time.


An image of a can of Red Bull energy drink.
Photo by Jesper Brouwers on Unsplash

In 1984, Austrian toothpaste salesman Dietrich Mateschitz, who was on a trip to Thailand, heard about an energy tonic created by Chaleo Yoovidhya which supposedly helped keep drinkers awake and alert. The two believed they could bring it to Western markets under the name of Red Bull — but unfortunately there was already a giant elephant in the room by the name of Coca-Cola.

Coca-Cola is a seemingly similar product — a sugary soft drink containing caffeine — and Coke was firmly entrenched as market leader. This was borne out in initial market research — people complained about Red Bull’s taste, its cost and the fact the can was smaller than a Coke. It looked like a bust.

What Mateschitz and co did was a masterclass in framing. They marketed it not as a soft drink, but an entirely new kind of product — an energy drink. They used a variety of methods, from aggressively giving out free samples on college and university campuses (keeps you fresh while studying or partying) to associating themselves with extreme sports through sponsorships and organising events.

Under this framing, the weaknesses became strengths. It tasted kind of like medicine because it has a “medicinal” effect. The smaller can is a sign of potency. It costs more because it has a function beyond being a refreshing fizzy drink.

Red Bull today is the category leader in the US energy drink market, even with Coca-Cola having launched their own competitive brand. In fact, if I say the phrase “energy drink”, most likely Red Bull is what comes to mind.

A picture frame held up in front of a coastal view
Photo by pine watt on Unsplash

A few common types of frames to consider using:

  • Value-based frames, where you appeal to shared understanding, principles, aspirations or experience. Tell a story that makes this connection. Value-based frames are good for building long-term commitment.
  • Material reward frames are about the direct, tangible (usually financial) reward. They are great for prompting action when you need to weigh up competing courses of action (your option earns us $X, my option earns us $2X, so we should pursue mine).
  • Gain-based frames are where you focus on the benefit of your approach. They’re best at creating behavioural change but pair poorly with risk, so you should talk about proof points (in software projects, incremental milestones are great) to mitigate risk aversion.
  • Loss aversion frames are where you focus on what the recipient will lose out on if they don’t follow your approach. They’re good for prompting timely action, and people tend to be less risk-averse when loss it at stake, so consider using these where you need something risky done in the near future.

A specific example of the difference between gain and loss frames comes from a review from the University of Minnesota from 2012. It finds that loss aversion frames are more effective in getting people to go to a cancer screening or STD test (where presumably people are misattributing the risk to the test itself), while gain focused messaging was more effective in getting people to make lifestyle changes which reduced their risk of disease. The effect sizes were small but significant, and were consistent across different mediums including print, audio and video.

A picture frame against a wall
Photo by Elena Joland on Unsplash

Some tips on framing your message:

Favour personal involvement over at-a-distance. Analysis by FrameWorks (a non-profit which studies communication of the social sciences) on public support of funding addiction assistance found that empathy — “we should feel sorry for drug addicts” — was ineffective, while “drug addiction affects us all and we need to work together to fix it” was more effective.

Metaphors are powerful. A 2011 study on US political attitudes towards criminal justice looked at the effect of being exposed to the message that crime was a beast preying on a fictional city, or a virus infecting that city. Those who’d been exposed to the beast messaging tended favour punitive approaches, and whose exposed to the virus messaging tended to favour reformative approaches — and this effect may be stronger than people’s pre-existing political beliefs or partisan affiliation.

A little negativity for empathy is OK, but you want the takeaways to be positive. A great example of this is Splunk: their ads lead with “Make on-call suck less”, which sounds good to any engineer who’s carried a pager — but immediately pivot to “Resolve incidents faster, minimize downtime and reduce the break-fix cycle”, painting the picture of the better world you could be living in while on-call.

Correcting mistakes can make them worse. A 2005 clinical trial from the University of Michigan showed participants two versions of a Center for Disease Control (CDC) pamphlet on influenza vaccines. One was “Myths and Facts”, focusing on debunking medical misinformation; the other was just facts. It found that after just 30 minutes participants were misremembering myths as facts and attributing them to the CDC! Focus on your own message, not disputing others’.

Use urgency sparingly. Urgency can be compelling, but only if it’s authentic rather than manufactured — and if you use it all the time, people will stop paying attention fast.

Empower people. Tell them how your approach gives them autonomy to reach their own goals. People are more resistant to things they feel have been imposed on them, even if they actually agree with the thing being imposed.

Include a call to action. Tell people what you want them to do next, and make it easy for them to do so.

Benefits, not features

The disassembled components of a digital camera
Photo by Vadim Sherbakov on Unsplash

One of the failure modes engineers tend to fall in to is lists of features — technical specifications of the devices we’re coveting (rather than what it does), or all the things we’ve delivered on a project (rather than the business outcomes), or things like that.

To illustrate this, let’s talk about early MP3 players. The first is the Creative Nomad Jukebox, which I had as a teenager. It’s the size of a CD player but with a 6GB hard drive, top quality audio, built-in equalizer, USB 2.0 (when that was a new thing) — all the bells and whistles.

Below is the first paragraph of the press release for that device:

The Creative Nomad Jukebox MP3 player

Creative Technology Ltd., the leading provider of Personal Digital Entertainment Solutions, today announced it has begun shipping the NOMAD® portable digital audio player to selected retail and e-tail outlets in the United States. The NOMAD® features a unique professional lifestyle design offering MP3 support with reprogrammable firmware to support future digital audio formats, software extensions, and standards. It offers consumers digital audio in style — anytime, anywhere.

Take a second to think about what’s good or bad about this statement. My personal thoughts:

  • It doesn’t use the word “music” or “song” once!
  • Why do I care where it’s shipping? Not that it tells me — “selected retail and e-tail outlets” is a contentless statement
  • There’s a lot of telling rather than showing on the design
  • Reprogrammability is niche
  • The only sentence which is good is the last one — that’s what the product actually is, and it’s buried

The second device is the Apple iPod. The original iPod was more expensive than the Nomad, had less storage, and only worked with a Mac. On the plus side, it was a smaller form factor and (arguably) easier to use.

Now, let’s take a look at the first paragraph of the iPod’s press statement:

The original Apple iPod

Apple today introduced iPod™, a breakthrough MP3 music player that packs up to 1,000 CD-quality songs into an ultra-portable, 6.5 ounce design that fits in your pocket. iPod combines a major advance in portable music device design with Apple’s legendary easy of use and Auto-Sync, which automatically downloads all your iTunes™ songs and playlists into your iPod, and keeps them up to date whenever you plug your iPod into your Mac®.

Take another moment to think about what’s good or bad here. My view:

  • Leading with the “why” is effective
  • Using visual or tactile statements (talking about “fits in your pocket”) is good
  • There’s still technical details, but always in the context of the problems it solves for you

Hopefully the point here is clear. Check out @chep2m’s post if you want to go really deep on the history of these devices, it’s fascinating stuff.

A question mark in neon graffiti
Photo by Emily Morter on Unsplash

Some tips to keep you focused on benefits rather than features.

Consider starting with “why” (h/t to Simon Sinek) rather than “what” or “how”. We discussed earlier that people make decisions based on emotion, and about supplying the narrative behind the action — the “why” is your chance to express your values and beliefs to make that connection, before going through the specific problem you’re trying to solve and how you’ll do it. Design reviews are a great example here — how much more compelling is the discussion if you go through what you’re looking to achieve and your principles for doing so, rather than just a list of work to do?

Use data, but sparingly. Data is a great tool, but if you overload people with it you’ll leave them confused and open your message up to misinterpretation — remember, our brains are wired to remember stories more than numbers. Figure out what data you need to add clarity and credibility to your story and get rid of the rest (at least up front).

Avoid jargon. Jargon is problematic for a number of reasons. If your audience doesn’t know the jargon, you open your message up to misinterpretation; you also risk making them feel either stupid or not part of the jargon-knowing in-group, neither of which makes you persuasive. You’ll feel tempted to because it makes you feel knowledgeable or part of that in-group — resist that feeling!

Make it personal. Think back to our MP3 players — in that paragraph, the iPod version uses “you” or ”your” 5 times, while the Nomad one has phrases like “it offers consumers digital audio in style”. Which one makes a better connection?

Connect your message to things in the real world, rather than the abstract. Saying something is portable sounds all fine and well, but saying it “fits in your pocket” is more evocative and hence likely to stick.

Keeping it short and focused

A lens held up in front of a lake background
Photo by Paul Skorupskas on Unsplash

Let’s briefly revisit our MP3 players from earlier. In addition to those press statements, they also had slogans for the devices — see if you can guess slogan belongs to which device:

  • 1000 songs in your pocket
  • Your entire music collection in the palm of your hand

Notice that these say almost exactly the same thing! But the first slogan (spoiler: that’s the iPod) is punchier and more memorable. Being concise doesn’t mean losing meaning, but if you can say the same thing with fewer words it’s almost always better.

Newspapers being printed
Photo by Bank Phrom on Unsplash

Next, I wanted to talk about the importance of focus in messaging using a story from my own career. As you might be aware, the move to digital has been massively disruptive for newspapers, magazines, periodicals and so on — less loyal readers, competition a click away and lower ad rates to name but a few of the challenges. The shift to mobile was making it worse at a rapid rate — and while publications like The Times and The Guardian could staff engineering teams to build out great apps and web experiences, that luxury was beyond the reach of most.

A few years back I was working on a project to help out publishers better leverage a modern tech stack (especially in distribution and monetisation) so they could focus on creating great content. One of our gimmicks was automatic app generation — you put in a few customizations for branding, hit the button, and presto — ready-made mobile app. We were proud of this and had a demo lined up with our exec sponsors.

One of the customizations available for the apps was brand colour — give it one colour and it’d generate a complementary palate. Unfortunately, the engineer driving the demo chose an unappealing shade of brown.

Anyone want to guess what the rest of the hour was about?

Not which publishers were our target audience, not which needs of theirs we were solving, not what competitors were doing, not what the size of the opportunity was. Everything was about whether and how to stop people picking colours we didn’t find aesthetically pleasing. What a waste of that valuable time!

When you’re pitching something to an audience with limited time and context — especially execs — they’re going to assume that what you put in front of them is the most important thing, that you want to talk about and get feedback on. Make sure it is, and get rid of anything else.

Repeat, repeat, repeat

The repeating torii gates at Fushimi Inari Shrine in Kyoto, Japan
Photo by pgaberski on Unsplash

The last topic we’re going to cover is repetition, persistence and consistency. To start us off, a quick pop quiz: what is Coca-Cola’s current slogan?

You can find the answer here, along with all their historic slogans. There’s a lot, so if you didn’t get it right you shouldn’t feel bad! There’s a couple of themes running through the list which probably informed what your guess was — “taste”, “real” — and it’s not like Coke has been unsuccessful in their marketing strategy (New Coke notwithstanding), but let’s look at Red Bull by way of comparison.

If you guessed that Red Bull’s slogan is “Gives you wings”, you’re actually wrong! They changed it in 2014 to “Gives you wiiings” in response to a lawsuit (apparently the change means they’re no longer making claims about efficacy, go figure). It almost certainly came to mind more easily than for Coke though— and it’s not just the longevity of the slogan. Red Bull’s entire marketing strategy reinforces it, from Felix Baumgartner’s near-space jump to stunt plane racing to Formula 1.

A repeating pattern of tiles
Photo by Mars Plex on Unsplash

There are a number of reasons to keep repeating your message.

First, the human brain reacts to repetition. We’ve known since the late 1800s that Spaced Repetition is the most effective way to learn and retain things — think flash cards for learning languages. It’s also well known in advertising that you want a message to be seen 3 to 20 times for the best chance of a conversion.

Second is clarity. If someone isn’t invested, or isn’t paying attention, or mishears — your message can miss its target. Think of how many emails, slack messages and random conversations you have in a day. When you say something more than once you give people more time to absorb and internalize the message. It also gives multiple opportunities to ask questions which can help clarify. This is why company initiatives will typically be an email, then a Town Hall presenting the same information as the email, then Q&A, then a follow-up summary and maybe also a blog post.

Third, it can help overcome passive-aggressive resistance. If a leader delivers a message only once or twice, people can resist simply by ignoring it. If they want to more actively resist, they can claim they didn’t hear or understand. If the message is repeated, it means these responses can be bypassed and you can get into properly resolving disagreements — or disagreeing and committing. Some techniques that help: varying your delivery with different mediums, different levels of detail, different tone; positive reinforcement, taking actions to support or recognize people engaging (including by disagreeing constructively); and leading by example, reinforcing your message through your own behaviour.

Fourth, inclusion. Being left out because you weren’t in the only team meeting where something was raised, discussed and decided is a lousy feeling. Making sure everyone has the chance to hear about things first-hand and ask questions is better for inclusivity.

Fifth, there’s ample evidence that for training, if you only hear about something once it’s very unlikely your behaviour will change. There’s a pertinent Chinese proverb: “I hear and I forget; I see and I remember; I do and I understand”. When I run workshops, we have exercises to put things into practice for this reason.

A project planning board using post-it notes
Photo by Brands&People on Unsplash

Putting this into some context for a software project, here’s where I suggest proactively communicating.

  • Say what you plan to do before you start (using OKRs or other goal setting framework)
  • Share your plan and get feedback (design reviews)
  • Give updates while you’re building (sync meetings, weekly emails, slack update channels)
  • Give updates when you roll out the feature
  • Give an update when it’s had time to see the effect on metrics, and what you’ve learned from them
  • Write up the effort at the end of your planning cycle, as part of your retrospective/planning cadence

This sounds like overkill. It’s not. People will not have all the context you do about your project, and aren’t living and dying by it like you are. If you don’t do something like this and feel you don’t get the support or recognition you should, then the harsh truth of it is you carry some — perhaps most — of the responsibility for that.

Worked Example

Photo by Brett Jordan on Unsplash

MegaService is a large backend system which powers all the most business-critical functions at MegaCorp — showing all of the company’s inventory to customers, pricing, checkout, business analytics, and more. It was first written about 10 years ago, on a tech stack which is no longer supported by the vendor and which you can’t hire anyone with that skillset any more. Product Management are frustrated that new features take so long to develop, and Finance are unhappy about how much it costs to run as compared to the modern microservice-based tech stack the newer parts of the business run on.

Your team has built a number of microservices which will replace the parts of MegaService you believe the business will need going forwards. You’ve put a lot of thought into the architecture and API design, and load testing has shown that it is cheaper, scales better and is operationally simpler — so that you won’t need dedicated production/SRE support.

MegaSRE are the team which keeps MegaService running. They don’t do any new feature development — nobody really wants to make changes to MegaService — but they fix anything and everything that goes wrong with it. They are all on the out-of-hours rota and all have many stories about the feats of heroism they’ve performed to prevent it falling over and destroying the whole business. Most of the team have only ever been on MegaSRE since joining the company, and for many this is their first job out of university.

MegaSRE are unhappy about the decision to decommission MegaService. They have complained that nobody except them knows how it works and that replacing a battle-hardened system with a bunch of new components is too risky. You’ve also heard some mutterings about how developers don’t care about actually running stuff in production and that your key new technology choice is just a fad.

Goal: get MegaSRE on board with the change.

Audience: MegaSRE team. It sounds like there’s concern about whether what they do is valued — nobody else makes changes to MegaService other than them, they talk about their heroics, they think developers don’t have the same values about running production services, and now the thing they own is going away and the replacement won’t need SRE support at all. They’re intimately familiar with the service and highly technical.

Framing: MegaSRE are currently thinking about this change as them losing something, maybe even losing their own identity. We’ll want to lead with recognition for their current efforts — maybe some negativity for empathy with their current situation — before anything else. Ideally, we want them to feel like the turndown is their goal as well — that they will work with the developers building the replacement, they’ll celebrate it as a joint success when done and will receive equal recognition and reward. We could appeal to values as well — maybe we find the SRE principles we can connect to on scalability and ability to more easily support (SRE isn’t about personal heroics!).

Benefits: leading with the tech, financial or operational benefits likely won’t work —that’s asking for an argument. Instead, we want to connect it to them and their values. I’d start with the SRE values as noted above, and if that lands pivot towards what they could do next after a successful turndown (which they’re sharing the credit for).

Repetition: The decision is already announced so we’ll want to do this in small groups. 121s and small team groups for discussion/AMA would seem best. MegaSRE starting to contribute to whatever regular project communications are being done for the turndown will be effective at reinforcing this.



Douglas Gresham

He/him. Currently Director of Engineering @ Skyscanner; formerly Google and FB.