The Overview page doesn't describe the problem to be solved. If it did that, I'd at least know whether I have that problem and could decided whether to continue reading.
This is an extremely common failing in technical writing. Without a clear problem statement, the reader has no clue whether the writing is worth the time. And without a clear answer to that question, most readers will do the rational thing and head for the exits.
Thank you for the term for that! I do it in most emails. First I write it the standard way, because that flows the most easily for me. Then I find the sentence with the request I'm making or key point I want to get across, move it to the top (or subject!), and edit as needed so the rest still makes sense.
I wonder if any science has been done on this - to me there seems a tradeoff. BLUF might work for executives that trust their reports. But it might be the exact opposite of what you need if you're trying to convince an audience of something counter-intuitive.
If you're going to be educated about a conclusion that is surprising or objectionable, would you rather be told the non-controversial premises first and then share in the reasoning process that leads to the conclusion? Or would you rather be told the conclusion first, and then unpack the argument from there? The latter seems like it could invite more opposition and waste more time.
Solution: stop trying to do the exact opposite of the thing that hurt, because big surprise, that’ll hurt too. I don’t understand why we have such a hard time figuring this out. Too much time sleeping through intro to logic, I suppose.
You start with an easy one to prove you’re not completely insane for considering this idea. You move to the hard ones to make sure you’re not going up a blind alley. By the time you’re done, they’ll all be easier (and if they aren’t, then pain is information. Use it.)
If you haven’t done the hardest one by the midpoint, odds are good someone is relying on wishful thinking. But doing the hardest one first is masochism.
Software is written by humans. Humans need confidence, and practice. Jumping into the deep end will just teach them not to try. People who can do the hardest one first? Aren’t looking for advice, and so you don’t need to write with them as the target audience.
Make sure you have the "critical path" in focus and have/create a plan to go along it. "Easy things are easy" and you can do them along the way as side projects. It's tempting to do bike shedding. Manage risks and uncertainties. Though all this requires you to be senior and well experienced and some companies just don't hire these kinds of people, because they are too expensive.
This is an extremely common failing in technical writing. Without a clear problem statement, the reader has no clue whether the writing is worth the time. And without a clear answer to that question, most readers will do the rational thing and head for the exits.
You might call this Problem-First Writing.