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.
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..
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.
> 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/
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?
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.
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.