Comment by brian_cunnie | Hacker News Reader

Comment by brian_cunnie | Hacker News Reader

Parent Full thread

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 ..."

> … 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)

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.

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.

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.

Even following a simple "who what when where why how" order of elaboration is extremely useful and clarifying.

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

Or any article from The New Yorker.

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.

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.

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.

Reply on news.ycombinator.com