Writing better by answering why, what, how

A neat guide for good technical writing goes as follows:<p>1. Tell the &#x27;WHAT&#x27; (i.e what you have built&#x2F;observed&#x2F;intend to do&#x2F;etc.)<p>2. Explain the &#x27;SO WHAT&#x27; without which the WHAT is almost meaningless (i.e. that it reduces operating costs by X&#x2F;...&#x2F;etc.)<p>I often find myself focusing too much on the WHAT, neglecting the SO WHAT. However, the succinct phrasing helps me to also keep the SO WHAT in mind.<p>(I first stumbled upon this way of phrasing things in the neat little book &#x27;Trees, Maps and Theorems&#x27; by Doumont)

Brilliant advise ! Well done, I like the almost algorithmic recipe here.<p>Speaking of writing, (sorry for slight high-jack) when writing your &quot;ad copy&quot;(yes I know it&#x27;s the devils work, especially on HN). But since we sharing writing tips :) Here is my ad-copy tip and litmus test<p>Can I <i>exchange company&#x2F;ad-subject</i> with one of my competitors and does the copy still make sense ? If yes then the ad&#x2F;sales-argument is NOT unique enough and usually bad.<p>Super Stupid example:<p>You own an &quot;Estate agency called Joe`s Family Homes and your ad-copy is:<p>&quot;At Joe&#x27;s We, Sell the best houses and get you in the right home for the lowest price&quot;<p>Meh... Very generic and you can exchange &quot;Joe&quot; for any of your competitors and the ad will still be true and make sense (and be crap).<p>A &#x27;better version&#x27; might be:<p>&quot;Joe Smith (From Joe&#x27;s Homes), who grew-up in your neighbourhood will not only get you in your next home, he probably went to high school with you and knows the in&#x27;s and out of this town&quot;

In a similar vein, my boss taught me to apply a similar strategy for writing effective emails:<p>1) Here’s what’s happening<p>2) This is what I need from you to address what is happening<p>3) This when I need it by.<p>4) Happy to answer any questions about the above.

now how do you get anyone to read your document? Is there some secret trick involved?

I hate amzn writing culture

&gt; Here’s a story from the early days of Amazon Web Services: Before writing any code, engineers spent 18 months contemplating and writing documents on how best to serve the customer. Amazon believes this is the fastest way to work—thinking deeply about what the customer needs before executing on that rigorously refined vision.<p>Good luck explaining this to the new age Scrum certified gurus who wants to complete all design work in 2 weeks of sprint 0.

&gt; Why - Expected ROI<p>Any guidance for quantifying this if you&#x27;re an engineer and don&#x27;t have access to financial numbers?<p>It&#x27;s hard for me to estimate the value of a feature I&#x27;m designing if the Product team just says it&#x27;s important without giving financial reasons. Presumably the feature will benefit the customer, but it&#x27;s hard to translate that into e.g. &quot;5% revenue increase&quot;

a friend recently gave me this same advice, and it does seem like a good idea.<p>i’ve been trying to rework my github readme’s to all start with why&#x2F;what&#x2F;how, and it&#x27;s hard! they should be concise, and yet sufficiently explanatory.<p>i’m not sure there is a why&#x2F;what&#x2F;how for all audiences. to get it right, you have to pick a subset of your potential readers and write for them. otherwise you trade concision for generality, and then lose some of your true target audience to boredom.

These are great sections to have - along with &quot;Who&quot; to delineate responsibilities between teams for say future maintenance in case several teams are involved.

Surely ‘Improve your writing by addressing The Why, what and how of your subject’ would have been more cromulent.