Hacker News Reader

Comment by JoeAltmaier | Hacker News Reader

My tech-write wife says the Engineer-writer fault she most often encounters is the 'mystery story'. That's hiding the lead down at the bottom of an argument. Because Engineers like to show their work and don't want to 'give away the ending' until they've proved it right.

So put the conclusion right at the top somewhere! Sometime its as simple as putting the last sentence of every paragraph at the beginning of the paragraph.

View on HN

It's about emails, but I like this article[0] about how topics are covered in the military (where I imagine clear communication is important). "Military professionals lead their emails with a short, staccato statement known as the BLUF (Bottom Line Up Front). It declares the purpose of the email and action required.". I find this helpful..

[0] https://hbr.org/2016/11/how-to-write-email-with-military-pre...

The BLUF is exactly analogous to what the internet hivemind calls the tl;dr (too long; didn't read). I almost always see the tl;dr as the last line of a long post, when really, it makes a lot more sense to lead with it.

Seconded. I always put TL;DR at the beginning if it's meant as an actual summary. I sometimes put a TL;DR at the end, when it's meant as a humorous summary.

It stands for "too long; didn't read." The operative word here is "didn't".

"If you started out trying to read this, but then realized it was too long and just skipped to the end, here is what you missed."

I have never understood why people put the TL;DR (I assume civ equivalent to BLUF) at the end. I don't want it at the end, I want it at the beginning!

I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status.

This sounds like a good piece of advice to keep in mind. It's nicer for the reader to not have to wait till the end to get what's going on.

People who design things, how do they make sure that what they are proposing is doable because we won’t know until a group of engineers finish the project and it goes into maintenance?

> I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status.

I agree, but maybe that style of writing has evolved for good reasons? In engineering, it seems to be a common personality trait that when presented with conclusions first, we tend to formulate reasons contradicting the conclusions, and then dig in on those reasons, to the detriment of trying to follow the explanations that follow.

In the military, on the other hand (which has been cited as an example of "bottom line first" culture in this thread), people seem more inclined to follow orders.

Anecdotally, in my limited time in the military, I had the opportunity of observing both kinds of personalities, and they did NOT mesh gracefully…

I really love this blogpost which discusses these two personalities, in the context of "corrections from strangers on Twitter". Some see corrections as "sharing information"; others see making corrections as asserting status/dominance which disrupts social harmony. https://status451.com/2016/01/06/splain-it-to-me/

Very insightful, thanks for sharing!

In college we learned to "spill the beans" in technical writing. Instead of:

> The goal was bla bla... We tried X... That showed Y. We tried Z, which sort of worked. At the end, we modified Z to work, achieving ABC.

should just be

> We achieved ABC toward our bla bla goal using a modified Z. [supporting lines]

This is something that I struggled with, good writers can build a story that reveals something over time. I'm not a good writer, I can't build stories like that, so I just have to lay the point out and support it after 5th grade form essay style.

There's a reason technical writing has the term 'technical' in it. It should be different from how one would writes for a casual audience (who are reading for fun). When reading as a hobby the mystery of where the story will lead to is part of the fun. But when reading a technical document you don't want there to be a mystery, you want to get the message as soon as possible. So it makes sense to have something upfront that tells the reader what the next couple sentences are about. I wouldn't see it as mediocre writing.

Reply on news.ycombinator.com