Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#101

Post by tombert » Fri, May 31, 2019, 4:28 PM UTC

sokoloff wrote: post #74

leesec wrote: post #61

Earlier quoted context omitted.

I find it bizarre that most people don't realize writing 'correctly' is just intelligence signaling too. There's no reason for it most of the time. If I can type something faster but still just as clear by typing it less-formally, I will often do so.

"but still just as clear" is a critical qualifier in your sentence. With that stipulated, I agree. When that is absent is when there's an issue. This is a not a matter of "Never end a sentence on a preposition." "This is the type of errant pedantry up with which I will not put."

Yeah, maybe I should have supplied a better example, since "when r u going to do this?" is fairly unambiguous, so I suppose that that is a failure of writing on my end :).

However, I've seen people us abbreviations that are incredibly difficult to parse, even for people with English as a first language. I can't imagine how difficult some of those emails can be for people that didn't grow up with the language.

Re: Undervalued Engineering Skills: Writing Well

#102

Post by growlist » Fri, May 31, 2019, 4:29 PM UTC

Agreed, hugely undervalued and I would argue pretty rare. My formal grammar is pretty poor and I mainly operate on what sounds right, but nonetheless I am commonly shocked by the basic mistakes that are made by most people including very senior people - poor punctuation, ambiguities, misuse of apostrophes etc. I don't know if this says something about education in the UK? But the main message to me is - things other than writing matter when it comes to getting ahead. Why bother showing it off or improving when it will likely just get you labelled as (if you can believe this still happens in a business like tech - but it does) a geek.

Re: Undervalued Engineering Skills: Writing Well

#103

Post by TomVDB » Fri, May 31, 2019, 4:29 PM UTC

qznc wrote: post #41

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…

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

I find that the most efficient way to get a point across is to use lists/bullet points in your email.

I have this very smart colleague who writes in long paragraphs and I always zone out somewhere in the middle.

It's a terrible way to figure out the essentials.

I much prefer PowerPoint diagrams that list the essentials over long paragraphs that include the gory details.

Re: Undervalued Engineering Skills: Writing Well

#104

Post by jlmorton » Fri, May 31, 2019, 4:30 PM UTC

> I have noticed a few skills that people often underestimate the importance of developing. Skills that add a significant boost to the impact of any developer. One of these ones is writing.

Heh.

Re: Undervalued Engineering Skills: Writing Well

#105

Post by the_af » Fri, May 31, 2019, 4:30 PM UTC

enriquto wrote: post #28

tombert wrote: post #17

Earlier quoted context omitted.

Oh, most of my coworkers are smarter than me, so I'm certainly not trying to make an assessment on their IQ or any nonsense like that. That said, I do think that writing smsesque (which I am going to steal for the future because I had never heard that term before) is a really good way to make yourself look dumber, especially to non-engineers. Even if my long and rambling writings lack substance, they still typically…

> I do think that writing smsesque (...) is a really good way to make yourself look dumber, especially to non-engineers. Maybe they do that in purpose, then?. They do not need to be admired by everybody, especially not by non-engineers. Like the very rich people who dress extremely humbly, with torn-down clothes.

My experience is that it's not on purpose and it's not signalling of any kind.

First, let me be clear: I'm lucky that I'm surrounded by smarter people than me. Almost all of my coworkers are incredibly intelligent people, can troubleshoot and code circles around me, and understand teamwork and building reliable software way better than me. It's a great situation to be in, because I have plenty to learn from them.

Unfortunately, they don't write very well in their native language (which is not English, by the way). They always ask me to proof read what they wrote. Full of typos and unclear sentences.

They also seem to be less well-read than me. Many don't read fiction at all; if they read anything, it's mostly books on tech. It's like their brain power is directed at other pursuits, and as a consequence their writing skill suffers.

Re: Undervalued Engineering Skills: Writing Well

#106

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

simonw wrote: post #5

The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like. This article is absolutely spot on when it points out that these skills become increasingly important as the size of an engineering organization grows. The biggest challenges in engineering at scale (scale in terms of complexity and size of the team) are around communication. Good writing is how y…

The problem is that many organizations prevent their IT/engineering departments from professionalizing in a way that would allow for this. "We need a month to iterate over requirements and specification" can land like a lead balloon in any project management meeting, because the _non_-engineers don't see any value in it.

Re: Undervalued Engineering Skills: Writing Well

#107

Post by kevan » Fri, May 31, 2019, 4:31 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?

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.

Re: Undervalued Engineering Skills: Writing Well

#108

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

la_barba wrote: post #88

beat wrote: post #76

Earlier quoted context omitted.

Most programmers simply do the tasks assigned to them, because most programmers don't know how to sell! If you can sell , then you get to decide what you should be working on, convince your manager (and team leads, and other managers, and business teams, and anyone else who might be a stakeholder or shot caller) that it is in their best interest to have you work on the thing you have recommended. Note that this can't…

Its not that I didn't understand your point. I just don't think this applies to most software engineers.

Understanding the problem domain, i.e. what the customers really want and need rather than just what they specifically ask for, will help any software engineer do their job better. Only then can you suggest alternative solutions that solve the real needs vs. patching one requested item after another that are all half measures to solving the real problems.

Re: Undervalued Engineering Skills: Writing Well

#109

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

This article pitches the idea that writing is an important skill to advance your career. It makes the point that you will be better at spreading an idea and influencing people.

I agree with this, but to me personally, the more compelling reason to improve your writing is that will improve your work (not necessarily your career).

It is more about better communication than influencing people. I want people to more easily and reliably understand what I am trying to communicate. Understand my ideas, my doubts, my suggestions, my attitude, my feelings.

My writing was definitely valuable in my transition to software development two years ago.

Re: Undervalued Engineering Skills: Writing Well

#110

Post by pickle-wizard » Fri, May 31, 2019, 4:32 PM UTC

piaromba wrote: post #96

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.

I too took a technical writing class in college and it was very helpful.

I used to be a pretty good technical writer early in my career. Everything I did was documented throughly. Anyone could read my documentation and pick up the project.

Then we had a management change. I would literally get yelled at by my director because I was wasting time creating documentation. So I stopped. Didn't document shit, and the yelling stopped.

I'm at a new job now, and I'm trying to get back in the habit of documenting everything. Though those skills are very rusty.