Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#91

Post by chuckgreenman » Fri, May 31, 2019, 4:19 PM UTC

JoeAltmaier wrote: post #62

My tech-write wife says the Engineer-writer fault she most often encounters is the 'mystery story'. That's hiding the lead down at the bottom of an argument. Because Engineers like to show their work and don't want to 'give away the ending' until they've proved it right. So put the conclusion right at the top somewhere! Sometime its as simple as putting the last sentence of every paragraph at the beginning of the par…

This is something that I struggled with, good writers can build a story that reveals something over time. I'm not a good writer, I can't build stories like that, so I just have to lay the point out and support it after 5th grade form essay style.

Re: Undervalued Engineering Skills: Writing Well

#92

Post by mlthoughts2018 » Fri, May 31, 2019, 4:21 PM UTC

I actually have found that if you are an engineer who displays well-rounded skills in multiple disciplines, like business acumen, communication, writing and conflict management, this causes managers and non-engineers around you to view you as a threat, and they will work harder to undermine you and try to box you into a “engineer only” label.

Above all, you won’t be rewarded for these other skills, despite how vital they are.

Re: Undervalued Engineering Skills: Writing Well

#93

Post by vidro3 » Fri, May 31, 2019, 4:22 PM UTC

second only to reading comprehension

Re: Undervalued Engineering Skills: Writing Well

#94

Post by sandGorgon » Fri, May 31, 2019, 4:22 PM UTC

mrmrcoleman wrote: post #32

Fully agree and I'd expand the point to cover communication in general. Explaining ideas clearly with text or voice is one of the characteristics that I've noticed in high-functioning engineering teams. I did a talk[1] a few years back about my experiences helping a team to improve their communication skills. What surprised me was the emotional complications that prevent people from communicating effectively. [1] htt…

Is there are tutorials or training material you would recommend. I have been hearing "plain writing" more and more...but not sure if it is the right thing.

Re: Undervalued Engineering Skills: Writing Well

#95

Post by C1sc0cat » Fri, May 31, 2019, 4:23 PM UTC

IggleSniggle wrote: post #75

C1sc0cat wrote: post #64

Earlier quoted context omitted.

The participants had not read the agenda, docs and done their actions before the meeting?

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.

Re: Undervalued Engineering Skills: Writing Well

#96

Post by piaromba » Fri, May 31, 2019, 4:23 PM UTC

I recall my technical writing class in collage was actually pretty good and it was a required course. But when i went into industry there was not monetary connection to writing quality. Sometimes it is even better for developers to have convoluted documentation because then they make themselves indispensable to maintenance in the future.

Re: Undervalued Engineering Skills: Writing Well

#97

Post by petra » Fri, May 31, 2019, 4:24 PM UTC

adenverd wrote: post #65

scarejunba wrote: post #60

Earlier quoted context omitted.

Interesting. Is the advice published externally somewhere? The Everything Store does mention the silent reading bit.

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

Re: Undervalued Engineering Skills: Writing Well

#98

Post by funkymike » Fri, May 31, 2019, 4:24 PM UTC

la_barba wrote: post #46

beat wrote: post #25

I used to be a huge proponent of learning to write well as the most important skill an engineer can learn. Now, I think it's the second most important skill. The most important skill is sales . The key value of writing well, in a workplace environment (or other environments, really) is to convince others to agree with what you're proposing. Convincing people that something they don't initially understand or trust is…

That sounds like a contrived scenario to me personally. Most programmers simply do the task that their supervisor or manager has assigned to them. Its not like they can refuse to do a task simply because it was worded poorly. They would just ask for further clarification.

Many tasks are poorly defined or aren't solving the real problems the customer has. This is the classic problem of a customer asking for something very specific then complaining when it doesn't solve their problem. There are a lot of developers who deliver exactly what is asked for in this way. They would be better served by taking a few minutes to make sure they understand how it serves the customers' actual needs, not just completing another ticket.

Re: Undervalued Engineering Skills: Writing Well

#99

Post by metamet » Fri, May 31, 2019, 4:26 PM UTC

C1sc0cat wrote: post #64

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…

The participants had not read the agenda, docs and done their actions before the meeting?

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

#100

Post by bongobongo » Fri, May 31, 2019, 4:27 PM UTC

I don't think this and other so-called "soft" skills are undervalued by engineers themselves. A good writer/communicator brings immediate value to any engineering team and will be treated as such, usually. It's the pointy heads and the business side of the operation who don't value it, because it's not sexy. IT and software engineering are abstract to them, so when they don't see "hands on keyboards" (writing code), they think no work is being done.

Software engineering will remain in its infancy as a "profession" until software engineers themselves organize and better assert their own professional standards. Writing and iterating over documentation is an ISO standard that is ignored 99% of the time. If you ignore your professional standards, you are not a professional, no matter your title or your salary or even your field of work.