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

61–70 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#61

Post by leesec »

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 find it bizarre that most people don't realize writing 'correctly' is just intelligence signaling too. There's no reason for it most of the time. If I can type something faster but still just as clear by typing it less-formally, I will often do so.

Re: Undervalued Engineering Skills: Writing Well

#62

Post by JoeAltmaier »

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

Re: Undervalued Engineering Skills: Writing Well

#63

Post by [deleted] »

yomly wrote: post #42
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…

It's a bit fuzzy whether people from CS backgrounds acquire this skill organically, but the style guide / format of the x-pager docs felt very familiar to scientific publishing. The main value of it felt that enshrining factual objective information and basing all discussion around that.

[deleted]

Re: Undervalued Engineering Skills: Writing Well

#64

Post by C1sc0cat »

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…

The participants had not read the agenda, docs and done their actions before the meeting?

Re: Undervalued Engineering Skills: Writing Well

#65

Post by adenverd »

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.

+1 would really love to read any style guides or writing class materials from Amazon, if anyone can share!

Re: Undervalued Engineering Skills: Writing Well

#66

Post by Veen »

ErrantX wrote: post #36
enriquto wrote: post #14

Earlier quoted context omitted.

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.

I think, in my experience, that there is a middle way which Ive seen the very best use (and try to follow). Fundamentally it is not about how much you write but how well you communicate. There is a difference in people that rattle off sms-style one liners every time, and those who know they only need one line to communicate fully. My experience is; the former style almost always leads to an email chain where one part…

Yes, it takes a little thought to write clearly and present the pertinent information, but it's plain bad manners to do otherwise.

Re: Undervalued Engineering Skills: Writing Well

#67

Post by C1sc0cat »

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.

Re: Undervalued Engineering Skills: Writing Well

#68

Post by franciscop »

I don't feel like it's undervalued; 93% of developers get frustrated by it:

- https://opensourcesurvey.org/2017/

It is a fairly thankless job because it's more difficult and the concept of bugs or missing features is fairly fuzzy (compared to software). But it is highly valuable, and people do notice it.

I attribute most of my open source popularity/stars at decent/good docs+examples in my libraries, like the most recent one:

https://github.com/franciscop/ola/

Re: Undervalued Engineering Skills: Writing Well

#69

Post by funkymike »

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.

Post reply on HN