Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#301

Post by alok-g » Fri, May 31, 2019, 11:37 PM UTC

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?

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

#302

Post by ducttape12 » Fri, May 31, 2019, 11:39 PM UTC

unfocused828 wrote: post #297

lpolovets wrote: post #188

Writing well is an undervalued skill in life, not just in engineering. When you work on a team of peers with similar skills in your field, whether that field is engineering or something else, being able to write well and communicate well become strong differentiators. FWIW, I'm pretty sure that writing (reasonably) well online is what got me a job in venture capital after ten years as an engineer. David Perell (host…

I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety? I genuinely don’t know how to find one. Therapist-shopping is baffling. I ask this as a software engineer who can produce pretty solid writing if…

I think any therapist who specializes in anxiety would be a good fit. Some studies show CBT (cognitive behavioral therapy) to be as effective as medicine.

www.psychologytoday.com has a search for finding local therapists. I'd start there.

And good luck! Feel free to reach out if you have any other questions.

Re: Undervalued Engineering Skills: Writing Well

#303

Post by thrower123 » Fri, May 31, 2019, 11:43 PM UTC

djakjxnanjak wrote: post #207

bloopernova wrote: post #184

Earlier quoted context omitted.

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.…

Maybe your colleagues perceive that they are being asked to study a bunch of off-topic material. Is reading RFC 2119 really the most productive use of their time?

If they can't be bothered to read and comprehend the two pages of RFC 2119, preferably in an hour or less, it raises grave doubts about their capacity to operate in a technical capacity. We kinda have to do a shitload of reading and understanding to know how things work - at least that is what I find myself doing most of my time.

Re: Undervalued Engineering Skills: Writing Well

#304

Post by everyone » Sat, Jun 01, 2019, 12:00 AM UTC

sixstringtheory wrote: post #232

everyone wrote: post #191

Earlier quoted context omitted.

Well the hypothetical manager would have no control over the images of people you apparently form for whatever reasons.

Solipsism. In communication, intent and perception are both factors that affect how the parties view each other. This is what "know your audience" means. > apparently form for whatever reasons I already gave you the reason: they aren't communicating professionally. They do have some control over how they project their image to others. After all, they're the one writing the message.

This is getting into the realm of philosophy. According to Stoicism, one has no control over others thoughts. I personally think thats a quite valid view.

I would evaluate a message from a manager by practical rubrics. 1. Clarity. 2. Comprehensiveness. 3. Terseness. Even those are fairly subjective, anything beyond that is so subjective it could counjour perhaps any image in someones head depending on the person. According my my rubrics above, the managers message was fine.

Re: Undervalued Engineering Skills: Writing Well

#305

Post by cosmie » Sat, Jun 01, 2019, 12:00 AM UTC

unfocused828 wrote: post #297

lpolovets wrote: post #188

Writing well is an undervalued skill in life, not just in engineering. When you work on a team of peers with similar skills in your field, whether that field is engineering or something else, being able to write well and communicate well become strong differentiators. FWIW, I'm pretty sure that writing (reasonably) well online is what got me a job in venture capital after ten years as an engineer. David Perell (host…

I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety? I genuinely don’t know how to find one. Therapist-shopping is baffling. I ask this as a software engineer who can produce pretty solid writing if…

I don't have that strong of a reaction, but realized fairly recently that I also get a lot of anxiety from writing on demand.

What works for me is not starting from scratch. If I do, I'll either never get it done or procrastinate until the last minute (while building up an incredible amount of anxiety in the interim).

Instead, I try one of two things:

1) Repurpose something else I have. As long as I have a seed to build off of or skeleton to frame against, I'm able to tackle it fine. If I have no frame of reference, I'll try to find one. In your self-evaluation case, I'd ask for an anonymous example from your boss or HR to understand the expectations.

Or, 2) Ask a trusted friend or colleague to check it over. My work context switches from C-level client management to architecture and analytics-related dev work. While I can articulate a matter to any audience, that also means I can completely miss the mark if I misjudge an audience/recipient I haven't addressed before. So I'll brain dump a bunch of stuff, then ask someone who's closer to the target audience or more familiar with them. They'll help act as a sanity check whether I'm on the right page, and I use their feedback to refine things.

I'm not sure if either of those coping strategies will help for you, but I wanted to mention them just in case!

Re: Undervalued Engineering Skills: Writing Well

#306

Post by everyone » Sat, Jun 01, 2019, 12:08 AM UTC

anchpop wrote: post #231

everyone wrote: post #81

Earlier quoted context omitted.

"when r u going to do this?" Why is that annoying? Its perfectly clear and concise. Good writing imo.

As with most things in life, it's about signaling. At work I always type with correct grammar to seem professional. On twitter I deliberately don't use capital letters or apostrophes to seem relaxed. Not because I actually care (and I don't care what anyone else does), but it influences how I'm seen. I really have no idea why it matters so much to some people, other than generic "its just our culture" arguments.

Seems like u are engaging in much that you are aware is unnecessary bullshit.

I personally wouldnt be happy doing that. I value intellectual honesty extremely highly for some reason.

Have you read this? I like it.

http://classics.mit.edu/Epictetus/epicench.html

Its an Enchiridion for Stoicism. Literally a handbook designed to be carried around and consulted as situations arise.

Re: Undervalued Engineering Skills: Writing Well

#307

Post by deathanatos » Sat, Jun 01, 2019, 12:20 AM UTC

bloopernova wrote: post #184

jsty wrote: post #4

I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write. Writing a couple of pages of design docs or an Amazon-style 6 pager or whatever might take a few days of work, but can save weeks or more of wasted implementation time when you realise your syste…

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.…

You might like the additional followup standard, RFC 6919: https://tools.ietf.org/html/rfc6919

> RFC 2119 defines a standard set of key words for describing requirements of a specification. Many IETF documents have found that these words cannot accurately capture the nuanced requirements of their specification. This document defines additional key words that can be used to address alternative requirements scenarios. Authors who follow these guidelines should incorporate this phrase near the beginning of their document:

> The key words "MUST (BUT WE KNOW YOU WON'T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919.

(Spoiler: this is an April 1st RFC. That said, I have wanted to use or used "OUGHT TO" so many times…)

Re: Undervalued Engineering Skills: Writing Well

#308

Post by occamsrazorwit » Sat, Jun 01, 2019, 12:26 AM 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…

Have you ever worked with a rockstar programmer whose code is unintelligible? Have you ever read something from a popular writer that was so wrong on a technical level? I wouldn't call either of those great.

Re: Undervalued Engineering Skills: Writing Well

#309

Post by deathanatos » Sat, Jun 01, 2019, 12:31 AM UTC

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…

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

#310

Post by gridlockd » Sat, Jun 01, 2019, 12:35 AM UTC

cosmie wrote: post #305

unfocused828 wrote: post #297

Earlier quoted context omitted.

I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety? I genuinely don’t know how to find one. Therapist-shopping is baffling. I ask this as a software engineer who can produce pretty solid writing if…

I don't have that strong of a reaction, but realized fairly recently that I also get a lot of anxiety from writing on demand. What works for me is not starting from scratch. If I do, I'll either never get it done or procrastinate until the last minute (while building up an incredible amount of anxiety in the interim). Instead, I try one of two things: 1) Repurpose something else I have. As long as I have a seed to bu…

I think the "starting from a frame of reference" is good, I wouldn't necessarily ask HR for what they expect. That's pushing them to commit to something, which they don't want to do either. Instead, look online.

Self-evaluation is just another piece of bullshit process where people's expectations are formed around the bullshit everyone is handing in. Chances are that what these people are handing in is highly informed by whatever the top Google results are.

Ordinary people don't necessarily have qualms about working this way, people with anxiety issues often have this misguided desire to be "original". Being unoriginal is fine though, it hooks into familiarity and it doesn't cause extra work. Nobody is excited about reading the performance reviews, it's just something to get done.