10 ms·

This is my writing gem: when you send an email, you either want them to know something or do something, so say that in the first sentence: Good: "FYI, our etcd

This is my writing gem: when you send an email, you either want them to know something or do something, so say that in the first sentence: Good: "FYI, our etcd cluster is broken, but we're working to fix it." Bad: "I came in this morning, and while I was going through my emails when I saw a message about one of the nodes in our cluster. So I checked it out, and sure enough it was down, and I went to the console and saw the kernel had panicked, so I ... [much further down] and that's when I realized our etcd cluster was down." The later is what I call The Narrative: people have a natural inclination to tell a story, but the irony is that usually what's at the end of the story is the thing that should be first ("the cluster is down!"). Similarly when asking for something: Good: "Could you please get me a new monitor? I'm getting headaches from the current one's constant flickering" Bad: "I had a headache yesterday, so I had to leave early—I hope that's okay. Anyway, I'm not sure about the purchase requisition process. I think there's a resonating frequency between the 60Hz electric system and my monitor's refresh rate, but I'm not an electrical engineer. By the way, the new chair is great ..."

iamstupidsimple 5y ago
A more generalised approach: structure emails in importance order, top down. So, actionable stuff at top, rationales further down, in descending importance etc... This becomes more critical when talking to execs.
MaxBarraclough 5y ago
For a masterclass in how not to write, take a look at this BBC article which is narrativised to the point of being downright insulting. [0] It's quite an effort to even figure out what they're talking about. (The article's dishonest clickbait title is just icing.) [0] https://www.bbc.co.uk/news/world-australia-49012771 https://www.bbc.co.uk/news/world-australia-49012771
- dqpb 5y ago
  Or any article from The New Yorker.
ciphol 5y ago
This is how journalists are taught to write. In a "pyramidal" style where the key facts come first, followed by elaboration, followed by more elaborate elaboration.
- deleted 5y ago
  [deleted]
- hammock 5y ago
  Even following a simple "who what when where why how" order of elaboration is extremely useful and clarifying.
kazinator 5y ago
Tell the story if the conclusion is unimportant, but there is a story to be told that is cool. Otherwise skip the story. If the story and the conclusion are important, give the conclusion and then hey, if anyone is interested, here is a story related to the conclusion.
ayewo 5y ago
> … but the irony is that usually what's at the end of the story is the thing that should be first ("the cluster is down!"). Also know as BLUF (bottom line up front). https://en.wikipedia.org/wiki/BLUF_(communication) https://en.wikipedia.org/wiki/BLUF_(communication)
synergy20 5y ago
Agree on most of the points here and the PDF. The only problem with me is that, the PDF itself is unnecessarily lengthy, which kind of weakening the point author is trying to make. Would be nice if it is in one or two pages.
hammock 5y ago
Agree with the general sentiment, and a constructive suggestion: >Similarly when asking for something. Good: "Could you please get me a new monitor? I'm getting headaches from the current one's constant flickering" Put the rationale ahead of the request. I.e. "My monitor is giving me headaches. It's affecting my work. Will you get me a new monitor? " This way you avoid the defensive knee-jerk reaction before you have made your case. Notice I also added a sentence of why your boss should care. A formula of two declaratives + a question is a good formula for short communications.
HeavyStorm 5y ago
Always open with an "executive summary". At most two sentences must convey all the information. Then you can add more details and narrative. This applies to email, PowerPoint, wiki pages, etc. It's a hard rule to follow - I'd risk saying that the "better" writer you are, larger the chance you'll drift into details and narrative. A good mechanism to solve that problem is to add the tl; Dr aka executive summary after you've written all you need. ---- Many years at Big Consulting Inc may have dried up my soul but at least taught me to communicate effectively, I think.

iamstupidsimple 5y ago

A more generalised approach: structure emails in importance order, top down. So, actionable stuff at top, rationales further down, in descending importance etc... This becomes more critical when talking to execs.

MaxBarraclough 5y ago

For a masterclass in how not to write, take a look at this BBC article which is narrativised to the point of being downright insulting. [0] It's quite an effort to even figure out what they're talking about. (The article's dishonest clickbait title is just icing.) [0] https://www.bbc.co.uk/news/world-australia-49012771 https://www.bbc.co.uk/news/world-australia-49012771

dqpb 5y ago
Or any article from The New Yorker.

ciphol 5y ago

This is how journalists are taught to write. In a "pyramidal" style where the key facts come first, followed by elaboration, followed by more elaborate elaboration.

deleted 5y ago
[deleted]
hammock 5y ago
Even following a simple "who what when where why how" order of elaboration is extremely useful and clarifying.

kazinator 5y ago

Tell the story if the conclusion is unimportant, but there is a story to be told that is cool. Otherwise skip the story. If the story and the conclusion are important, give the conclusion and then hey, if anyone is interested, here is a story related to the conclusion.

ayewo 5y ago

> … but the irony is that usually what's at the end of the story is the thing that should be first ("the cluster is down!"). Also know as BLUF (bottom line up front). https://en.wikipedia.org/wiki/BLUF_(communication) https://en.wikipedia.org/wiki/BLUF_(communication)

synergy20 5y ago

Agree on most of the points here and the PDF. The only problem with me is that, the PDF itself is unnecessarily lengthy, which kind of weakening the point author is trying to make. Would be nice if it is in one or two pages.

hammock 5y ago

Agree with the general sentiment, and a constructive suggestion: >Similarly when asking for something. Good: "Could you please get me a new monitor? I'm getting headaches from the current one's constant flickering" Put the rationale ahead of the request. I.e. "My monitor is giving me headaches. It's affecting my work. Will you get me a new monitor? " This way you avoid the defensive knee-jerk reaction before you have made your case. Notice I also added a sentence of why your boss should care. A formula of two declaratives + a question is a good formula for short communications.

HeavyStorm 5y ago

Always open with an "executive summary". At most two sentences must convey all the information. Then you can add more details and narrative. This applies to email, PowerPoint, wiki pages, etc. It's a hard rule to follow - I'd risk saying that the "better" writer you are, larger the chance you'll drift into details and narrative. A good mechanism to solve that problem is to add the tl; Dr aka executive summary after you've written all you need. ---- Many years at Big Consulting Inc may have dried up my soul but at least taught me to communicate effectively, I think.