Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#141

Post by draw_down » Fri, May 31, 2019, 5:06 PM UTC

sixstringtheory wrote: post #124

ryanmcbride wrote: post #57

Earlier quoted context omitted.

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

Well, let's read each other charitably instead of doing this sort of thing, shall we? GP is not describing a binary choice but rather a set of priorities.

A lot of what is called "good writing" is really just a collection of signifiers that don't have anything to do with expressing ideas clearly or succinctly. There are plenty of people who would die before ever writing "y'all" but would gladly take 7 paragraphs just to get to the fucking point.

GP is describing a preference for clarity and succinctness over those signifiers.

Re: Undervalued Engineering Skills: Writing Well

#142

Post by valbaca » Fri, May 31, 2019, 5:09 PM UTC

petra wrote: post #97

adenverd wrote: post #65

Earlier quoted context omitted.

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

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, 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

#143

Post by mont » Fri, May 31, 2019, 5:09 PM UTC

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…

Also I'm not sure how useful it is to test people on remembering minutiae of a system on the fly. How often are you correct about small details of a system you work with on a daily basis on the first try?

Re: Undervalued Engineering Skills: Writing Well

#144

Post by asdffdsa » Fri, May 31, 2019, 5:13 PM UTC

sokoloff wrote: post #79

qznc wrote: post #41

Earlier quoted context omitted.

I don't care if you write "you" or "u". I do care a lot about clear definitions in technical writing. For example, someone could mention a "system". What exactly does he mean? Is it synonymous to "the servers" he mentions in the next paragraph? Or is there an important difference? Even worse if people do not even read the text and only look at the diagrams. Hours of meetings could be replaced with minutes of reading.…

And units ! Please both put the units in writing and make sure they're correct! Your network does not run at 100 milli-bits per second. A byte (B) is a lot bigger than a bit (b). Mega (M) is not the same as milli (m). Term contract prices are typical per month or per year, so when you tell me the contract is "only $25K", you haven't told me anything. Tell me it's "$25K/yr" or "$25K/mo" and you've told me something.

And acronyms!

Re: Undervalued Engineering Skills: Writing Well

#145

Post by thfuran » Fri, May 31, 2019, 5:16 PM UTC

ragona wrote: post #129

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.

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.

Re: Undervalued Engineering Skills: Writing Well

#146

Post by cwbrandsma » Fri, May 31, 2019, 5:16 PM UTC

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 am all of those as well, but learned coping mechanisms. Like proofreading like crazy and reading aloud.

Still can't spell tho, and homonyms will be the death of me.

Re: Undervalued Engineering Skills: Writing Well

#147

Post by mailslot » Fri, May 31, 2019, 5:17 PM UTC

This is literally how I get “impossible” changes to happen virtually anywhere. There’s so much psychology that goes into the impact of the written word.

Don’t spread my secret. :(

Re: Undervalued Engineering Skills: Writing Well

#148

Post by ealfert » Fri, May 31, 2019, 5:21 PM UTC

petra wrote: post #97

adenverd wrote: post #65

Earlier quoted context omitted.

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

And even if you can't publish, but can recommend some other material with close-enough content, that would be great.

"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

#149

Post by wool_gather » Fri, May 31, 2019, 5:21 PM UTC

duxup wrote: post #133

funkymike wrote: post #69

Earlier quoted context omitted.

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

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

#150

Post by d23 » Fri, May 31, 2019, 5:23 PM UTC

amirhirsch wrote: post #119

Did anyone else find this article to consist of ironically poor writing? The blog post contains of a lot of fragments, run-on-sentences, unnecessary pauses, mixed tenses, dangling clauses, use of the passive voices, and no Oxford comma!

I'm surprised this is so far down. I'm assuming most people commenting didn't actually read it and are just agreeing with the sentiment.

Perhaps the author is not a native language speaker? That being said, I'm not sure why you'd write an article about the importance of writing if your writing is... below average at best.