Write clearly
I'm doing a lot more digital communication in the post-Covid world. We all are, right?
I'm going to compare and contrast some communication styles—my dreams and my nightmares.
Be the change you want to see in the world.
Don't bury the lede
- To begin a story with details of secondary importance to the reader while postponing more essential points or facts.
I'll highlight this with two real-world examples.
❌ Unclarif.io
Here's an announcement leaked from the Slack workspace of the tech giant Unclarif.io.
As you all know, incident management is critical to meeting our SLAs. It's vital that all teams are aligned in our incident management process so that incidents can be responded to and resolved in a timely manner.
Last year, a decision was made to unify our incident management process under an internal tool, Incidentify. All teams were asked to review, evaluate, and migrate to our the new Incidentify tooling. This decision was made with the best information available at the time in regards to cost, performance, and developer experience.
The shifting market has given us an opportunity to let our commitment to agility shine as we re-evaluate last year's decision to migrate to Incidentify. It is now clear that the best path forward is to unify our incident management with observability monitoring under our existing observability tooling, Metrics Mouse. Please keep this in mind during your Q2 planning as the deprecation date for Incidentify is on the horizon...
✅ Clarifi.land
And here's a similar announcement from their competitor, Clarifi.land.
👀 ⚠ Stop migrating to Incidentify. Start migrating to Metrics Mouse.
August 31st is the last day for Incidentify. The Incidentify team is terminating all Incidentify infrastructure on August 31st.
Metrics Mouse has secretly been working on an incident management tool that they just announced. Bob from the Incidentify team and CTO Clair evaluated Metrics Mouse's offering and concluded there was massive value added by having incident management tightly integrated with observability. We're also getting a huge cost savings because of our existing contract and early adoption...
But Eric...
You picked examples that were intended for two different audiences. The second example, with its direct instructions, is apparently targeted specifically towards engineering teams. The first example is apparently targeted towards a wider organizational audience.
Maybe.
But how often do you see the two get mixed?
Never mind. It doesn't matter if you answer that. If you're pointing this out, then you understand the take-away.
When you need to communicated deadlines and required actions, don't bury the lede. Put that info front and center.
If you want to provide details and reasoning and context around a decision then do that after you've told people what they need to do.
Also. You say "But Eric..." and then imply that the first example is "ok" because it's written for a wider organizational audience. But why is it ok for "wider organization" communications to be vague and to obscure the important details? Maybe the wider organization doesn't care as much about the dates because they don't have to take action. But every line that your audience ignores conditions them to ignore the lines that you need them to read. Ditch the fluff.
"I did this" vs. "This was done"
I'm going to quote a lot from Eliezer Yudkowski here because his words are clearer than mine.
Writers are told to avoid usage of the passive voice.
If I hadn't primed you with the heading of this section, you might not see the flaw in that sentence. The sentence doesn't clarify who tells authors to avoid usage of the passive voice.
Consider the second sentence of the Declarif.io's announcement.
It's vital that all teams are aligned in our incident management process so that incidents can be responded to and resolved in a timely manner.
Why is it vital? To whom is it vital? How is our existing process not "timely"? Compare the previous statement to the following alternative.
Last month, the shipments team called on our CTO, Charles, to help resolve an incident. Charles had access to shipments' incident tooling but not warehouse's and that resulted in missing an obvious correlation. A 1 hour recovery turned into a 1 day recovery.
Or in the words of Eliezer...
Passive voice removes the actor, leaving only the acted-upon. “Unreliable elements were subjected to an alternative justice process”—subjected by whom? What does an “alternative justice process” do? With enough static noun phrases, you can keep anything unpleasant from actually happening.
...
It sounds more authoritative to say “The subjects were administered Progenitorivox” than “I gave each college student a bottle of 20 Progenitorivox, and told them to take one every night until they were gone.” If you remove the scientist from the description, that leaves only the all-important data. But in reality the scientist is there, and the subjects are college students, and the Progenitorivox wasn’t “administered” but handed over with instructions. Passive voice obscures reality.
Embrace the active voice. Honor the additional context that it freely provides. Invoke emotion.
We should have ...
Don't say this.
We should have an alert for when that happens.
That should have logged an error.
The server should restart itself in situations like this.
What do you mean?
Do you mean that you know <topic> doesn't exist and that it would be good for <topic> to exist? Furthermore, are you expecting someone to take action on this? (But not you?)
Or do you mean that you expected <topic> and that you're surprised that <topic> isn't working?
Or are you indignant about current state of the system yet accept it—because you know why it is the way it is or because you know it can't be changed?
This first one seems to be the most common case. It reminds me of the parable The Mice in Council.
In the story, a group of mice agree to attach a bell to a cat's neck to warn of its approach in the future, but they fail to find a volunteer to perform the job. The term has become an idiom describing a group agreeing to perform an impossibly difficult task.
Ok. Maybe "impossibly difficult" is stretching it.
But my point is that it's not fair to suggest action be taken without knowing why it hasn't already been taken. It's also not fair to suggest that action be taken without specifying by whom (and why the "whom" isn't you).
Anyways. Whatever meaning you intended to convey, you're not conveying it clearly.
Try these alternatives.
I'll assign myself to a ticket to add logging for that error case.
Great. This isn't vague. Problem clearly communicated and already resolved.
I added an alert last week which I expect would have caught the issue as you're describing it.
Now I know that 1. you're not suggesting I go create an alert for this, 2. I can go check if there's a defect with the existing alert, and 3. there might be something unique about this situation which makes it different from whatever past experiences led us to create the existing alert.
Any provider worth a grain of salt would have automatically restarted the server in this situation. My frustration with <service provider> is unbounded.
Yes, my friend. I share your pain.