Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#161

Post by hyeomans » Fri, May 31, 2019, 5:34 PM UTC

beat wrote: post #58

hyeomans wrote: post #45

Earlier quoted context omitted.

Do you have any good resources on sales?

Start with How to Win Friends and Influence People , by Dale Carnegie. Ignore the cheesy-sounding title; this book was written in the 1930s and has been in print continuously ever since, which speaks to its effectiveness. I also recommend To Sell Is Human , by Daniel Pink (and all of Daniel Pink's other books, as well).

Thank you. I try to re-read How to win friends every year, there's always a nugget of information that I remember.

I bought To Sell is Human, thank you for that one.

Re: Undervalued Engineering Skills: Writing Well

#162

Post by mattjaynes » Fri, May 31, 2019, 5:34 PM UTC

Basically, here is what I tell myself when I'm going to write something for an audience:

• Nobody gives a fuck ABOUT ME or how cool or awesome I am.

• People only care about how awesome THEY ARE.

• I am competing for their very short attention-span. Facebook, Netflix, and porn are my competition. This better be pretty compelling if they are not going to immediately hit their back button.

• I either need to address some real PAIN they have, or be pretty amazing at entertaining them. In most cases, addressing a real pain is easier. It's much harder to entertain better than porn, breaking news stories, etc.

• Structure for pain is clear:

1. Identify the pain and show how much it hurts and costs them

2. Show them the solution, and how good it will feel to stop losing and start winning

3. Anticipate and address their concerns. Are they worried about cost? Are they worried about how much work it will require? Are they worried what their boss or customers will think? Etc. Think of the most likely concerns or objections they will have and explain how to resolve them. All or most of their questions should be answered so that there is nothing in the way for the next step...

4. Call them to action to do something. Use your tool. Change a behavior. Etc.

The structure can vary a bit, but this is generally the structure. In a purely technical article, you may have very short sections on the pain, then spend most of the time on the solution. If the purpose is more for sales, then you'll want to have it more balanced and focus a lot on resolving concerns.

The article should be clear enough and structured enough so that every paragraph can have a headline. And a reader should be able to scan the headlines and know very quickly and clearly without having to think "what is this article about?"

If the article feels or looks like work to read, they will give up right away and you've lost them. There has to be something really compelling for them. How will this make them more awesome? They don't give a fuck about anything else.

They are milliseconds away from hitting their back button or searching for "nude guitar solos", so put the effort in to deliver something compelling and valuable. One well-thought-out clear useful article is far greater than a hundred jumble-thought aimless ones.

Edit: formatting

Re: Undervalued Engineering Skills: Writing Well

#163

Post by criddell » Fri, May 31, 2019, 5:35 PM UTC

mnorton wrote: post #24

I have kept around and distributed multiple copies of The Elements of Style, by Strunk and White, for the past few years (lots of revisions of this out there, 4th might be most recent iirc). It's like a 9$ book and the guidance is priceless. https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...

If you've read Steven Pinker's book Sense of Style, I'd be interested to hear where it falls short in comparison to Elements of Style.

Re: Undervalued Engineering Skills: Writing Well

#164

Post by ecyrb » Fri, May 31, 2019, 5:37 PM UTC

valbaca wrote: post #142

petra wrote: post #97

Earlier quoted context omitted.

And even if you can't publish, but can recommend some other material with close-enough content, that would be great.

I've taken the class within Amazon. Honestly there isn't anything that you couldn't get by simply reading and applying the advice from "The Elements of Style" by Strunk and White[1] and "On Writing Well" by Zinsser [2]. The primary philosophy is that if you can't write well, then you haven't thought it through. The act of writing is an act of reasoning. 0. Practice in a strong feedback loop. This applies for anything…

I found "Style: Toward Clarity and Grace" [1] by Joseph M. Williams to be more informative than both of these recommendations, but YMMV. There is a newer version, but I haven't read it.

[1]: https://smile.amazon.com/Style-Clarity-Chicago-Writing-Publi...

Re: Undervalued Engineering Skills: Writing Well

#165

Post by Nimitz14 » Fri, May 31, 2019, 5:39 PM UTC

chuckgreenman wrote: post #91

JoeAltmaier wrote: post #62

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 par…

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.

Re: Undervalued Engineering Skills: Writing Well

#166

Post by peter_retief » Fri, May 31, 2019, 5:40 PM UTC

Good software skills are good writing skills

Re: Undervalued Engineering Skills: Writing Well

#167

Post by dv_dt » Fri, May 31, 2019, 5:40 PM UTC

funkymike wrote: post #69

mabbo wrote: post #27

Amazon is obsessive about this stuff. I'm surprised the article never mentions it. There are internal classes offered on writing better documents (and it's a great class). There's videos, guides, documents, everything. Writing well at Amazon is key to a successful career here. Got a project idea? Write a very good 1-pager explaining it and you've got a much higher chance of it actually happening. Want to share a desi…

> I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting. I wish this could happen where I am. No one wants to bother reading anything ahead of the meeting to be prepared for a discussion. Then the same people don't have the patience to let the group review the material during the meeting before starting the discussion.

I think this flourishes only because it comes from the top of Amazon, with Bezo's being the top proponent of this writing-first communication process.

Re: Undervalued Engineering Skills: Writing Well

#168

Post by Kiro » Fri, May 31, 2019, 5:41 PM UTC

wool_gather wrote: post #151

mabbo wrote: post #27

Amazon is obsessive about this stuff. I'm surprised the article never mentions it. There are internal classes offered on writing better documents (and it's a great class). There's videos, guides, documents, everything. Writing well at Amazon is key to a successful career here. Got a project idea? Write a very good 1-pager explaining it and you've got a much higher chance of it actually happening. Want to share a desi…

I like this idea on the surface. The flipside though is that if everyone's reading the doc for the first time right before discussion, it doesn't allow for much depth of analysis. Do you also send the materials out beforehand?

Sending it out beforehand defeats the purpose.

Re: Undervalued Engineering Skills: Writing Well

#169

Post by samirm » Fri, May 31, 2019, 5:41 PM UTC

tombert wrote: post #6

I do find it a bit bizarre that the otherwise smart people that I work with, with English as their first language, will often resort to writing emails and documentation like a 14-year-old on AIM. I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers. I'm hardly Jo…

>I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers.

This might seem paradoxical at first, but upon further inspection you realize that those who learn a language (as opposed to acquire it) are better at it.

Re: Undervalued Engineering Skills: Writing Well

#170

Post by fooblitzky » Fri, May 31, 2019, 5:45 PM UTC

Another undervalued skill is speaking well. Since joining Toastmasters my career has undergone a step change. Managers perceive me as being much more effective, even though my writing and coding skills have only continued growing incrementally. It's the best investment of time I've ever made.