Writing better by answering why, what, how | Hacker News Reader

Writing better by answering why, what, how

eugeneyan.com

278 points7d7n34 comments

A neat guide for good technical writing goes as follows:

1. Tell the 'WHAT' (i.e what you have built/observed/intend to do/etc.)

2. Explain the 'SO WHAT' without which the WHAT is almost meaningless (i.e. that it reduces operating costs by X/.../etc.)

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.

(I first stumbled upon this way of phrasing things in the neat little book 'Trees, Maps and Theorems' by Doumont)

“So what” is otherwise known as why. And it often flows better if you put it before the what – why is it that you’re doing the what and why should I care?

Another good writing tip: replace every “and then” transition with a “and that’s why” or “and despite that” transition

> “So what” is otherwise known as why.

It's valuable to phrase it as "so what" rather than as "why", because people without focus in all fields end up writing only "why the thing being analyzed happened" and not "why this analysis/suggestion/whatever matters". The problem with "why" is that "why"ing the wrong thing ends up just being an extension of the "what". Or at least be up front and clear and say in its entirety "why you need to stop whatever else you are doing right now and listen to me". Writing advice can improve itself by careful attention to writer failure modes.

> And it often flows better if you put it before the what

Indeed. You want to quickly convince the reader to stick around. But often you need to give a little background first, so really it becomes "what, so what, what for real, how, etc"

> “So what” is otherwise known as why.

These are often different. "Why" is often interpreted to mean why the author did it, while "So What?" or "Why Should I Care?" is why the audience should care and continue reading.

I think this is a really useful way of analysing your argument and refining it, as long as you question whether that really is why.

If the form is applied thoughtlessly, there's a risk it's gonna feel like the prose equivalent of Corporate Memphis illustrations.

=> https://en.wikipedia.org/wiki/Corporate_Memphis

Announcements where personality has been deliberately injected seem to have a habit of beginning with a pithy-but-vague mission statement, immediately followed by “that's why” and then an unwelcome operational detail:

> Here at {company} we know you value {vague nice thing like fairness or something}. That's why we're sunsetting our 64 petaquux widgets, and transitioning all of our customers over to our popular 32 petaquux widgets, in order to enhance your experience.

If you believe what you're saying but you're struggling to articulate it, borrowing a form can help you along, but you really can't manufacture genuinely persuasive writing.

I am not sure “so what” equates to “why” in my mind. “Why” tells the cause of the “what”. “So what” explains the reason one should care about the “what”.

> replace every “and then” transition with a “and that’s why” or “and despite that” transition

The creators of South Park give the same advice for writing fiction: every two beats in your story should be linked not by an "and" but by a "but" or "therefore".

https://www.youtube.com/watch?v=vGUNqq3jVLg

what you're describing is Rolfe's reflective model in the pedagogical literature.

You're missing the 3rd step, which is "Now What?"

Example:

What: - What happened? - What was your role in the situation? - What were you trying to achieve? - What actions did you take? - What surprised you?

So what: - So, what have you learnt? - So, what was the importance of this learning? - So, what more do you need to know about this? - So, what broader issues have arisen from the situation?

Now what: - Now, what could you do to enhance/improve the outcome? - Now, what might you do to repeat this success in the future? - Now, what might be a consequence of your chosen course of action?

Brilliant advise ! Well done, I like the almost algorithmic recipe here.

Speaking of writing, (sorry for slight high-jack) when writing your "ad copy"(yes I know it's the devils work, especially on HN). But since we sharing writing tips :) Here is my ad-copy tip and litmus test

Can I exchange company/ad-subject with one of my competitors and does the copy still make sense ? If yes then the ad/sales-argument is NOT unique enough and usually bad.

Super Stupid example:

You own an "Estate agency called Joe`s Family Homes and your ad-copy is:

"At Joe's We, Sell the best houses and get you in the right home for the lowest price"

Meh... Very generic and you can exchange "Joe" for any of your competitors and the ad will still be true and make sense (and be crap).

A 'better version' might be:

"Joe Smith (From Joe'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's and out of this town"

In a similar vein, my boss taught me to apply a similar strategy for writing effective emails:

1) Here’s what’s happening

2) This is what I need from you to address what is happening

3) This when I need it by.

4) Happy to answer any questions about the above.

One of my mentors very astutely pointed out that the military, or at least the Air Force, is commonly said to run on 3 things:

- Excel spreadsheets

- Emails

- Threats

Having spent some years as a commissioned officer I wholeheartedly concur that what you've got there is the best way to get things done in a large org. A single well-crafted email can have significantly outsized effect.

The only thing I commonly added was a 5th clause (or an addendum to #3) detailing the consequences should the person not grant your request.

This works both up and down the chain of command, but don't forget to add something in the vein of "for your consideration sir/ma'am" if addressing a superior officer.

Funnily enough my boss learned it from a mentor who was a former military officer.

I forgot about the consequences clause, but partially because I work in a team where we’re the ones sent into the address the consequences. So our consequence is an implicit “and “What’s Happening Keeps Happening.” Which is always fun but I recognize can be a bad habit once I (hopefully) stop firefighting.

I like your comment because it actually contains some other email best practices. 1) Keep it really really short. 2) Use bullet points (numbers are better than bullets)

I find this works great in 1:1 communication. Inverting 1 and 2 has been more successful for me on communication to a larger audience.

Example:

Need to update windows by tonight or you won't be able to log in. Because x xploit.

Compared to:

We have been notified of x xploit. We all need to update windows by tonight.

But good framework.

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

Here's how it's done at Amazon: schedule an hour long meeting with the people you want to read it. Make sure that the meeting invite includes no description or agenda, and has only a vague subject. If anyone declines your meeting invite, forward the invite to their manager and say they are blocking you by not joining your meeting. Do not provide a link to the document until 1-5 minutes before the meeting starts.

During the meeting, spend the first 5 minutes giving people access to the doc (which is made stupidly difficult because you're using the worst collaboration software known to the tech industry: Quip). Spend the next half hour in silence while everyone reads the document for the first time. Then spend 20 minutes going over the comments left on the doc, bikeshedding about minor details. Finally, spend the last 5 minutes talking about how you ran out of time to discuss the important topics and have to schedule a second meeting while everyone groans.

Ok, now does that mean that only a program managers can get his documents into consideration?

Are those page memo still six pages long?

One thing I've found is that outside the formal design cycle its often nice to write short technical memos to document some small portion of what you're working on. It could be a feature, it could be why the CI is setup the way it is. If anyone asks a question about some technical subject you have written about, give them a short answer, but point them to your written document and invite more questions if anything is unclear. If you get repeated questions on something that isn't written up, it's a good clue it might be useful.

Also nice if your org has some internally searchable wiki or doc repository. Having a commonly designated "Tech Memo" area can be helpful too, though often the best place for it is near the code it describes or that you've set out to build.

I hate amzn writing culture

Can you explain why?

As someone at another large tech company we often hear about it and I wonder if a version of it would help improve our work style.

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

Good luck explaining this to the new age Scrum certified gurus who wants to complete all design work in 2 weeks of sprint 0.

Slow is smooth and smooth is fast.

I don't know how to reconcile this with my view of amazon.

"the customer" to amazon is not only the customer buying products, but the "other customer" paying for search results. The interests of the two are in opposite directions. I wonder if they have some sort of laffer curve.

This is more an AWS thing, I imagine, where the business is providing the client with cloud computing resources in a secure and efficient manner. That at least seems to be a straightforward goal (although I wonder about how their billing really works under the hood, I imagine there are ways to push customers into more expensive tiers than they really need).

Amazon, the warehouse & shipping outfit, is riven with conflicting interests and is probably something of a nightmare to work as a dev at because of that. Current legislation exposes this:

> "The bill, co-sponsored by Sens. Amy Klobuchar (D-Minn.) and Chuck Grassley (R-Iowa) would stop sites including Amazon and Google from giving their own products a leg up in search results. (NYPost Jun 2022)"

Also, consider the people responsible for Amazon's "Time on Task" warehouse worker monitoring system... kind of sadistic at best.

> 18 months

That's either an utter lie or one very specific research project not performed by the "engineers".

Yeah, unless they mean some other Amazon than the one that believes in "2 > 0" in product portfolio management and that "communication between teams is terrible!" (a quote attributed to Jeff Bezos).

Granted I don't know the context of the given quote, but I definitely agree with at least one interpretation of it. If you need communication and synchronization between teams to achieve your goal, there's a lot more room for missing memos, misunderstanding etc. In that sense indeed, communication between teams is terrible in the sense that it adds extra drag to the whole process. Of course, there's ways to spin this quote in a number of other ways too, which is why I think the quote without any additional context doesn't really illustrate any one point.

The linked article spells out exactly what project it was about:

> Take AWS. It reached $10 billion in revenue in less than four years. But what's remarkable is that they didn't get there by forming a team, writing a lot of code, and then testing and iterating. In fact, it took more than 18 months before the engineers actually started to write code. Instead, they spent that time thinking deeply about the customers they were trying to serve and forming a clear vision for what AWS should be

> Why - Expected ROI

Any guidance for quantifying this if you're an engineer and don't have access to financial numbers?

It's hard for me to estimate the value of a feature I'm designing if the Product team just says it's important without giving financial reasons. Presumably the feature will benefit the customer, but it's hard to translate that into e.g. "5% revenue increase"

I wish I had a straightforward answer for you. This is an important question to quantify, in order to justify the scope and timeline for building features. As an engineer, I always believed that there’s some version of the “no free lunch theorem” applicable to building product roadmaps (and as an extension identifying pertinent product features). Meaning, you can’t reasonably predict what features are going to work, and how well they’re going to work to translate that to $$$. If I could take a guess, I would build out a framework to accurately guesstimate the value of a feature as follows. A brute-force approach to build out a free —> paid feature funnel: 1. Launch a beta or a “free” version of whatever feature you’re building. This could be as hand-wavy as conducting focus groups and doing proper UI/UX research to validate there’s “some amount” of interest in your user base. 2. Tighten the scope and refine the feature to make it as seamless as possible. Check the app/usage stats and KPIs to ensure people actually derive value out of your features albeit not actually paying for it now. 3. Start charging for it. And see how many people will actually pay for this well-refined feature. Do this long enough, your company should have some baseline numbers for all of these steps. %conversions on steps 1 —> 2 —> 3 and therefore, better ways to estimate the “why”.

a friend recently gave me this same advice, and it does seem like a good idea.

i’ve been trying to rework my github readme’s to all start with why/what/how, and it's hard! they should be concise, and yet sufficiently explanatory.

i’m not sure there is a why/what/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 "Who" 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.

Reply on news.ycombinator.com