News for hackers. Stuff that matters.
Re:Undervalued Engineering Skills: Writing Well by mabbo on Friday May 31, 2019 @11:38AM (#20061876)
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 design? Write a 6-pager (often 10-15 pages with appendices) explaining what, why and how you're going to build the system.

I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting.

It's very weird for newcomers, but I don't know anyone who finds that it isn't better than the alternatives.

Re:Undervalued Engineering Skills: Writing Well by funkymike on Friday May 31, 2019 @12:07PM (#20062165)
> 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.

Re:Undervalued Engineering Skills: Writing Well by mabbo on Friday May 31, 2019 @02:25PM (#20063622)
This is exactly the point of the silent reading time. Stop lying to yourself and others by saying you'll read ahead. You won't. No one will. Or worse, everyone but one person will and he'll have "skimmed it" and then ask questions that are on page 2, wasting everyone's time.

If you want to bring this to wherever you work, I encourage it. All you need to do is lead the meeting yourself with a strong, assertive voice. Tell them this is what we're doing. When someone inevitably complains just ask them to please wait to ask questions until everyone is done.

Re:Undervalued Engineering Skills: Writing Well by duxup on Friday May 31, 2019 @12:57PM (#20062682)
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.
Re:Undervalued Engineering Skills: Writing Well by wool_gather on Friday May 31, 2019 @01:21PM (#20062956)
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 possible."

If somebody really needs my time, they can tell me why -- or go through my manager which they should be doing anyways.

Re:Undervalued Engineering Skills: Writing Well by deathanatos on Friday May 31, 2019 @08:31PM (#20066289)
You say that, and it sounds like it ought to work, and yet…

I had to do that to a co-worker, and all I got back was "Product Foo". Okay, but what about Product Foo? Blood from a stone, every damn time, and it wears me down.

Re:Undervalued Engineering Skills: Writing Well by wool_gather on Saturday June 01, 2019 @12:36PM (#20069987)
Well, that kind of reply is just rude, and personally I'd probably ignore it and leave the meeting declined. If it comes up later, "Your reply about the meeting? No, I don't think...oh, I did see it, right. I assumed there was more info coming; I'm totally focussed on $X right now, you know."
Re:Undervalued Engineering Skills: Writing Well by AlexCoventry on Saturday June 01, 2019 @12:46AM (#20067293)
"I'm sorry, my responsibilities don't leave me any time to discuss Foo in general terms at the moment. If you really you need me to, please raise it with $manager, and we will reprioritize my duties."
Re:Undervalued Engineering Skills: Writing Well by duxup on Friday May 31, 2019 @01:27PM (#20063008)
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 by dv_dt on Friday May 31, 2019 @01:40PM (#20063152)
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 by Topgamer7 on Friday May 31, 2019 @12:11PM (#20062192)
Bake it into the meeting.
Re:Undervalued Engineering Skills: Writing Well by JustSomeNobody on Friday May 31, 2019 @12:42PM (#20062521)
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 by dkasper on Friday May 31, 2019 @12:57PM (#20062693)
Sounds like you need to change teams.
Re:Undervalued Engineering Skills: Writing Well by yomly on Friday May 31, 2019 @11:46AM (#20061964)
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.

Re:Undervalued Engineering Skills: Writing Well by wool_gather on Friday May 31, 2019 @01:24PM (#20062989)
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 by alok-g on Friday May 31, 2019 @07:37PM (#20066078)
You'll be amazed how good people at Amazon become at reading with experience. The discussion comments that come out are often fabulous.

On the other hand, I am indeed able to add a lot more value as a reviewer if I can read the document ahead of the time. So whenever I am the prime reviewer, I request the document to be sent one day ahead of meeting even if it is incomplete at that time.

Re:Undervalued Engineering Skills: Writing Well by r00fus on Friday May 31, 2019 @01:28PM (#20063015)
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 by samirm on Friday May 31, 2019 @01:32PM (#20063070)
I don't see how this would prevent depth of analysis?
Re:Undervalued Engineering Skills: Writing Well by sokoloff on Friday May 31, 2019 @02:30PM (#20063673)
How could I do any off-line research into the topic or a specific point in your paper if I've only seen it for the first time in the meeting?
Re:Undervalued Engineering Skills: Writing Well by samirm on Sunday June 02, 2019 @11:30AM (#20076065)
You do it with your laptop in the meeting...
Re:Undervalued Engineering Skills: Writing Well by sokoloff on Sunday June 02, 2019 @01:58PM (#20076958)
That imposes two problems: that I am limited to about 15 minutes of research time (limiting depth and basically eliminating "phone a friend" consultations) and it requires that one permits laptops into the meeting.

Nevertheless, I'm a supporter of the approach and have introduced it into the most important review meetings that we hold in my group. (We do bar laptops and other electronics, other than video conferencing equipment.) Results after 18 months seem quite positive on balance.

Re:Undervalued Engineering Skills: Writing Well by wool_gather on Friday May 31, 2019 @02:42PM (#20063796)
Generally people need some time to ponder new input in order to grasp edge cases, work through implications, identify unspoken assumptions, and so on. Some extraverted folks are happy to "think out loud" in a group, but even then it's too easy for a conversation to move quickly past a particular point that deserves more time.
Re:Undervalued Engineering Skills: Writing Well by samirm on Sunday June 02, 2019 @11:31AM (#20076070)
I agree that needing time for analysis is important, but what's preventing you from working through all of this during the meeting?
Re:Undervalued Engineering Skills: Writing Well by vkou on Friday May 31, 2019 @01:28PM (#20063013)
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 by Kiro on Friday May 31, 2019 @01:41PM (#20063165)
Sending it out beforehand defeats the purpose.
Re:Undervalued Engineering Skills: Writing Well by wool_gather on Friday May 31, 2019 @02:43PM (#20063804)
How so? Couldn't you do both?
Re:Undervalued Engineering Skills: Writing Well by scarejunba on Friday May 31, 2019 @12:01PM (#20062105)
Interesting. Is the advice published externally somewhere? The Everything Store does mention the silent reading bit.
Re:Undervalued Engineering Skills: Writing Well by ragona on Friday May 31, 2019 @12:42PM (#20062524)
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 by adenverd on Friday May 31, 2019 @12:04PM (#20062131)
+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 by petra on Friday May 31, 2019 @12:24PM (#20062336)
And even if you can't publish, but can recommend some other material with close-enough content, that would be great.
Re:Undervalued Engineering Skills: Writing Well by valbaca on Friday May 31, 2019 @01:09PM (#20062823)
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, not just writing.

1. Ruthlessly reduce your sentences. Repeat until you can't eliminate or combine any more words.

2. Avoid adverbs. Use "dashed" or "sprinted" instead of "ran quickly". Learn more words.

3. Avoid weasel words like "should" "could" "might". Take a stance and give concrete reasons.

4. Use concrete data over descriptors. "+5% profit" over "increased profit".

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

6. Use the simplest word that maintains your meaning. No one needs to use the word "utilize".

[1]: https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...

[2]: https://www.amazon.com/Writing-Well-Classic-Guide-Nonfiction...

Re:Undervalued Engineering Skills: Writing Well by ben509 on Friday May 31, 2019 @03:31PM (#20064161)
#0 is correct. I'll recommend this piece on S&W [1] and specifically on point #5 [2].

These style guides, especially points #1 through #6, came about from bureaucrats who were essentially filibustering or otherwise obfuscating in their writing.

The root problem there was not the long-winded writing, it was their intent to hide bad things.

If you can make sure you're not carrying water for corrupt officials, you best strategy is to try to write natural prose. Yes, do look for wordy phrases or cliches, but don't obsess over adverbs or the passive voice.

[1] https://languagelog.ldc.upenn.edu/nll/?p=15509 [2] http://itre.cis.upenn.edu/~myl/languagelog/archives/003366.h...

Re:Undervalued Engineering Skills: Writing Well by Veen on Friday May 31, 2019 @06:38PM (#20065703)
Geoffrey Pullum (author of the language log article you link to) also has an excellent set of videos explaining why most advice about passives is bunkum.

https://youtu.be/suAASPc_s0A

Re:Undervalued Engineering Skills: Writing Well by criddell on Friday May 31, 2019 @01:29PM (#20063028)
> 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 by mabbo on Friday May 31, 2019 @02:38PM (#20063757)
This is awesome. Even after the class I found it so hard to do this and this trick is going to really help. Thanks for sharing it!
Re:Undervalued Engineering Skills: Writing Well by ecyrb on Friday May 31, 2019 @01:37PM (#20063108)
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 by valbaca on Friday May 31, 2019 @02:39PM (#20063773)
Thanks for the suggestion (and for using AmazonSmile!)
Re:Undervalued Engineering Skills: Writing Well by ealfert on Friday May 31, 2019 @01:21PM (#20062952)
"Note: GeekWire’s Todd Bishop prepared this memo in the traditional style of an Amazon ‘six pager’ — fictional press release, narrative, FAQ and appendix — for Amazon Consumer CEO Jeff Wilke and the audience at the GeekWire Summit, where Wilke will speak Oct. 10, 2017."

Article: https://www.geekwire.com/2017/prepared-6-page-memo-geekwire-...

6-Pager Example: https://cdn.geekwire.com/wp-content/uploads/2017/10/Jeff-Wil...

Guidelines: https://blog.usejournal.com/writing-docs-at-amazon-e02580861...

Previous HN Discussion: https://news.ycombinator.com/item?id=19115686

Re:Undervalued Engineering Skills: Writing Well by sandGorgon on Friday May 31, 2019 @12:16PM (#20062240)
+1 on this.

Any info on what the writing class covers ?

Re:Undervalued Engineering Skills: Writing Well by yomly on Friday May 31, 2019 @12:39PM (#20062489)
My (personal) tl;dr from it was:

- Some light style rules about having no qualifiers e.g. words like "really significant" were banned

- Keep language super concise and non-flowery. Don't try to sound clever, Keep It Simple, Stupid for language basically

- Structure arguments a bit like the Minto pyramid[0] was another one I was told while there

- No one cares how much work or effort went into your doc, or how clever it is, only the final artefact of your work/thought should make it into the doc no matter how concisely you can express it

[0] https://www.amazon.co.uk/Pyramid-Principle-Logic-Writing-Thi...

Re:Undervalued Engineering Skills: Writing Well by petra on Friday May 31, 2019 @12:19PM (#20062273)
>> 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 ?

Re:Undervalued Engineering Skills: Writing Well by vkou on Friday May 31, 2019 @01:30PM (#20063036)
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 by C1sc0cat on Friday May 31, 2019 @12:04PM (#20062126)
The participants had not read the agenda, docs and done their actions before the meeting?
Re:Undervalued Engineering Skills: Writing Well by IggleSniggle on Friday May 31, 2019 @12:12PM (#20062208)
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 everyone is on the same page. Since everyone is presumably going to need to read the docs at some point anyway, incorporating the activity doesn’t really seem like a waste of time to me.
Re:Undervalued Engineering Skills: Writing Well by Consultant32452 on Friday May 31, 2019 @12:41PM (#20062512)
I've been writing software professionally for about 20 years. I'm not sure I've ever been to a meeting where most of the attendees have prepared by reading relevant materials including documents attached to the meeting invite. Because of this experience, I have a very different expectation. I attach documents to the meeting invite so that people can know where to find it for reference during but mostly after the meeting.
Re:Undervalued Engineering Skills: Writing Well by C1sc0cat on Friday May 31, 2019 @12:23PM (#20062318)
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.

Re:Undervalued Engineering Skills: Writing Well by r00fus on Friday May 31, 2019 @01:32PM (#20063065)
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 by sokoloff on Friday May 31, 2019 @12:09PM (#20062186)
This process is designed to ensure that the docs have been read and have been freshly read. I think of it as moving the time and effort into a defined and nearby time, and it's far from a "waste" of time, IMO.
Re:Undervalued Engineering Skills: Writing Well by metamet on Friday May 31, 2019 @12:26PM (#20062359)
Only somewhat related here, but we recently did a QP where our team came in without previously breaking epics into smaller tasks.

One argument is that we could've done that outside of the meeting, in its own meeting. But that actually wouldn't have saved any time, but would've probably cost more. Basically, we set aside the afternoon to accomplish the task at hand. If we had broke it into multiple days, there would've been memory debt we'd have to refresh.

As an engineer, I feel that requiring pre-homework for a meeting can be detrimental. As other posters mentioned, going through it all together in the scheduled meeting ensures that everyone is on the page. Additionally, it means that an hour long meeting doesn't actually require an hour and a half of my time, so I can better judge and plan my schedule.

Re:Undervalued Engineering Skills: Writing Well by mabbo on Friday May 31, 2019 @02:31PM (#20063681)
Amazon is also big on "mechanisms over good intentions".

Asking everyone to please do these actions before the meeting is a good intention. Everyone wants to, but you know things happen and well I skimmed it but I didn't really have time and now I'm going to ask questions that page 2 answers clearly because I didn't read it. Everyone's time is wasted.

Forcing everyone to spend 15 minutes right now is a mechanism. It's much more effective.

Re:Undervalued Engineering Skills: Writing Well by kevan on Friday May 31, 2019 @12:31PM (#20062404)
People read the agenda and complete action items before the meeting, but the expectation is that everyone reads the doc at the start of the meeting.