News for hackers. Stuff that matters.
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...