A brief example of tailoring words for different listeners: engineers and managers

Here’s how I’d usually phrase a story, which is a quite objective narrative:

We have 2 CI servers: A weak one and a strong one. Our PRs trigger a Job on the weak server. [System diagram here]

The disk on the weak server frequently becomes full, and — each time — an engineer needs to manually clean up the disk.

That chore usually takes 10 min and is a waste of time. An engineer’s average salary amortizes to $60/hr, so we’re losing $10 every time this happens.

Had the PRs been triggering the Job on our strong server instead, which has 10x the disk space, we could’ve reduced the frequency to 10% and the amortized loss to $1. We should migrate the Job. The migration should take ~1 hour.

That’s engineer speak, suitable for communicating with senior engineers and tech leads. Nearly all the sentences have an object as the subject. There are numbers, but not emotions.

Suppose we are talking to a manager (who’s been quite rusty in engineer speak), can we phrase this better?

This morning, Alice can’t get her PR validated on the CI server. Yesterday, it happened to Bob. And the day before that? Cindy. [Screenshots of chat messages here]
None of them know as much about the servers as Dave, so that’s who they turned to for help.

Dave explained that, “the PR validation process runs on our weak server, and the disk was full.” and he went on to clean up that server.

Dave did that three times in a row, and it’s just this week. He’s got better things to do, like that killer feature due next Monday. We don’t want to risk missing a million-dollar launch, not this time, and also not in the future, do we?

If we move that validation Job from the weak server to our strong server, which has 10x the disk space, we wouldn’t have this trouble anymore. It only takes 1 hour to migrate, and it will save us tons of risks in the long run.

The characteristics of this statement are as follows:

• Start with a description of the current predicament rather than a bland background.
• Talk more about people and less about things. Of course, avoid judging others. Focus on what kind of trouble they’re in. This evokes sympathy.
• Exaggerate the impact, if necessary. “Millions” is more gripping than “$9.”
• Negative emotions can shock others more than positive emotions. Compared with an optimization of “cost-saving”, the risk of “missing a product launch” calls for more action.

At this point, you might start to wonder: What kind of incompetent managers deserve this degree of babysitting? They probably don’t in the tech industry, but not every engineer work at a tech company. They might be in retail, fashion, film production, etc., where there just happened to have a need for software development. Even those who do work in tech might wish to move to an industry that is less tech-centric, at which point these communication skills will prove handy.