Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Undervalued Engineering Skills: Writing Well

blog.pragmaticengineer.com

Post reply on HN
Print view View original

121–130 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#121

Post by JustSomeNobody »

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.

People won't read ahead, so you all have to get up to speed on the doc, during the meeting, then some jerk manager who is always late comes in and makes us all repeat the same discussion. The meeting ends up taking all the time just to cover what is in the doc but no decision gets made because we ran out of time.

Re: Undervalued Engineering Skills: Writing Well

#122

Post by ragona »

scarejunba wrote: post #60
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…

Interesting. Is the advice published externally somewhere? The Everything Store does mention the silent reading bit.

If you search for "amazon narrative writing style" you'll find all kinds of articles.

The way that I personally explain this to new Amazonians is that I want their documents to tell a story. Now, I'm in engineering so the the story is going to be about some kind of highly technical topic, but it should start with an introduction, and it should lead the reader to the point that they have a pretty solid understanding of the problem space. If we put a document in front of a leader who has never even heard of our team before they should walk away understanding what the problem we're trying to solve is. That's part of what makes it so hard -- writing for an audience that might not be familiar with ANY of your internal jargon.

The documents must also be quite dry; they should avoid unnecessary adjectives, opinions should be called out as such, etc. Don't say, "high throughput," say, "72k TPS." That kind of thing.

Re: Undervalued Engineering Skills: Writing Well

#123

Post by apo »

I noticed the article appears to contain a single point of evidence supporting its main claim:

> Don't take this advice just from me. Take it from others, like employee #8 and now SVP of engineering at Google, Urs Hölzle who also says that writing clearly is an important superpower for engineers.

The link goes to a LinkedIn page with a brief quote captured in raster image format. This is weak evidence for a topic that will certainly be met with strong resistance from the target audience.

The author could make a much stronger case by interviewing a few people at top companies specifically on the topic of engineer writing. These people should be in a position of making promotion decisions. The author might coax out of them illustrative anecdotes that show exactly how poor writing skills can keep an aspiring engineer down.

How much money in lost wages is my crappy writing costing me? What are my job prospects if my writing doesn't improve? What exactly will better writing allow me to do that I can't already do? These are all questions that demand answers (and evidence) from people with 10 other things they might be doing.

Another idea: what studies (if any) have been done on the correlation between writing quality and promotion within technical organizations? For that matter, how does one objectively measure writing quality? After all, you're much more likely to improve something you can measure.

A hallmark of good writing (of any kind) is ample evidence to support claims. Engineers and scientists are a skeptical bunch, and so this point applies even more to technical writing.

Re: Undervalued Engineering Skills: Writing Well

#124

Post by sixstringtheory »

ryanmcbride wrote: post #57
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'll take a conversational email with sms shorthand and emojis explaining a bug effectively over the business major crap emails I get 30 times a day complete with greetings, farewells, oxford commas, correctly used semi colons that don't actually tell me what the problem is or what the repro steps are.

Have we arrived at the place where we have to choose one or the other? Because I choose option 3: where people do their jobs relatively well, with some amount of professionalism (which I used to think was a necessary, but not sufficient, part of doing your job well).

Re: Undervalued Engineering Skills: Writing Well

#125

Post by draw_down »

enriquto wrote: post #14
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 used to think like that (being the kid that wrote well in school). But now I'm not so sure anymore... Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.

Yes, same here. Ultimately what matters is ideas and concepts, not their particular mode of expression.

And certainly, taking someone’s ability/inability to write as a general sign of their intelligence or empathy or level of talent is a mistake.

Re: Undervalued Engineering Skills: Writing Well

#126

Post by xrd »

Popular opinion almost makes it seem like "writing well" (for human consumption) is almost the opposite of "writing good code" (for computers).

To be regarded as a great programmer, you need to know all the arcane details of a system, where those are the intricacies of a particular language or framework, or the small details of how a computer system works. It's the minutiae that counts.

With writing for humans, you need to have a very high level overview of things. You need to speak broadly and appeal to a common human understanding. The top level understanding is what matters.

Coding interviews reflect the change the industry is sensing and what this author puts well: the worst coding interviews are where they ask you about some small detail of a language or algorithm. It's a gotcha test. The better interviews ask you to show how you holistically approach a problem.

Re: Undervalued Engineering Skills: Writing Well

#128

Post by siculars »

I say it all the time: a significant fraction of my job is to read and write google documents. I’m either writing docs or I’m reading/commenting on docs someone else wrote.

Reading and writing are foundational skills needed in virtually every field. Especially especially especially at google.

/I work at google/

Re: Undervalued Engineering Skills: Writing Well

#129

Post by ragona »

xrd wrote: post #126

Popular opinion almost makes it seem like "writing well" (for human consumption) is almost the opposite of "writing good code" (for computers). To be regarded as a great programmer, you need to know all the arcane details of a system, where those are the intricacies of a particular language or framework, or the small details of how a computer system works. It's the minutiae that counts. With writing for humans, you n…

I disagree -- there are many situations in which your writing must display both a very detailed understanding of a system, AND a very detailed understanding of your audience.

Re: Undervalued Engineering Skills: Writing Well

#130

Post by xrd »

C1sc0cat wrote: post #67
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…

You know that a lot of us in the Biz are on the spectrum Dyslexia, Dyspraxia etc - writing can be F ^ g Hard.

I don't identify as any of those D's. And, I'm not discounting your experiences with writing.

I wrote a book (http://shop.oreilly.com/product/0636920043027.do) and it was the hardest thing I ever did.

I love this quote from Thomas Mann: ""A writer is someone for whom writing is more difficult than it is for other people."

Keep at it, even though it tears you to shreds. It's worth it. It tears everyone who does it to shreds. You aren't alone in the way you feel about writing and you can do it too.

Post reply on HN