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

151–160 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#151

Post by wool_gather »

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?

Re: Undervalued Engineering Skills: Writing Well

#152

Post by duxup »

wool_gather wrote: post #149
duxup wrote: post #133

Earlier quoted context omitted.

I WANT TO read ahead, but nobody tells me even what meetings are about despite having company wide meetings on effective meeting and the first point was about setting agendas and seating meeting goals and topics.

I've found just declining these no-info meetings to be an effective way to combat the time loss. It's most constructive to send an email alongside saying something like "please share an agenda or materials for this", but that can vary based on context too. And you can even decline after that happens: "Thanks for the details. I'm sorry, but I cannot take the time away from X right now to attend this. Next week may be…

If that's an option, yeah I think that is a really good route.

It wasn't in my situation, mostly because everyone sucked at meetings at an astounding level. But I'm not there anymore thankfully!

Re: Undervalued Engineering Skills: Writing Well

#153

Post by vkou »

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?

It's much better then the traditional design review, where 80% of the participants spend less than 5 minutes reading the doc before discussion.

Re: Undervalued Engineering Skills: Writing Well

#154

Post by r00fus »

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?

Perhaps in a competitive/demanding culture, this is the best you can get.

Besides, very few people in decision making positions have time to study all the prep material beforehand. I sure as hell don't do that when I have back-back-back meeting schedules.

Re: Undervalued Engineering Skills: Writing Well

#155

Post by criddell »

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…

> 5. Write in active voice. Look up the "by Zombies" trick.

This is something I struggle with so I took your advice and found this:

https://www.grammarly.com/blog/a-scary-easy-way-to-help-you-...

Thanks!

Re: Undervalued Engineering Skills: Writing Well

#156

Post by vkou »

petra wrote: post #90
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…

>> Write a very good 1-pager explaining it and you've got a much higher chance of it actually happening. Who does this 1-page explainer go to ? who is the gate-keeper ?

Your boss, or his boss. They are a gate keeper, in the sense that they can choose whether or not to fund your idea - or, if they are already on board with funding your idea, they need some concrete document that they can show to their peers, to get them to help you/agree with this prioritisation.

Re: Undervalued Engineering Skills: Writing Well

#157

Post by ragona »

thfuran wrote: post #145
ragona wrote: post #129

Earlier quoted context omitted.

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.

And, similarly, you can code perfectly functional code that properly handles all the minutiae but is totally inconsistent with the general structure or style of the project and that is bad. The high-level considerations are still important there.

Agreed! The intersection of coding and communicating is really interesting. That is my personal bar for a really phenomenal programmer — someone who can produce code that communicates ideally to both humans and computers.

And this gets harder and harder depending on the task! It’s really tricky stuff.

Re: Undervalued Engineering Skills: Writing Well

#159

Post by r00fus »

C1sc0cat wrote: post #95
IggleSniggle wrote: post #75

Earlier quoted context omitted.

I had the same initial reaction, but then again...doing it during the meeting, always, ensures that all participants are at least talking about the same thing. I’ve been in meetings where it doesn’t become clear until very late that someone is bullshitting and has not actually read the materials, or read them so lightly that their comments/opinions are not well directed. This is, imho, much worse than making sure eve…

That is assuming that the bullshitter or another participant doesn't understand what they read. Also sounds like the Chair did not control the meeting.

Sometimes there is no clear or a weak "chair". Furthermore, if the bullshitter is influential enough that you don't have time/capital in-meeting to call their BS? That's why BS is successful.

I see the Amazon approach as an augment to the chair to keep the discussion on-topic. If it's not discussed on the paper, the burden is on the dissenter to provide info / present credentials to rebut.

Re: Undervalued Engineering Skills: Writing Well

#160

Post by samirm »

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?

I don't see how this would prevent depth of analysis?
Post reply on HN