Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Undervalued Engineering Skills: Writing Well

blog.pragmaticengineer.com

Post reply on HN
Print view View original

41–50 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#41

Post by qznc »

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.

Even worse if people do not write text at all but only PowerPoint diagrams. What is the meaning of the boxes and arrows? Is it consistent?

Maybe the responsibility should be placed on the readers as well? They should demand better writing.

Re: Undervalued Engineering Skills: Writing Well

#42

Post by yomly »

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…

It's a bit fuzzy whether people from CS backgrounds acquire this skill organically, but the style guide / format of the x-pager docs felt very familiar to scientific publishing.

The main value of it felt that enshrining factual objective information and basing all discussion around that.

Re: Undervalued Engineering Skills: Writing Well

#44

Post by Crinus »

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.

No they do not. I've seen a LOT of smsesque text that come from all sorts of different people who i'm 100% they are not trying to "appear dumber". I do not know why people do it, so i assume laziness. Smart people can be lazy too.

Re: Undervalued Engineering Skills: Writing Well

#45

Post by hyeomans »

beat wrote: post #33
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…

And as a follow-on comment rather than an edit... There's nothing smarmy or dishonest about sales. Misleading sales is bad sales. The best salespeople are focused on fulfilling the customer's needs, not selling the product. The product sells itself once the customer understands that it fulfills their needs and offers them real benefits relative to the expense. And expense isn't just money. It's time. It's risk. It's…

Do you have any good resources on sales?

Re: Undervalued Engineering Skills: Writing Well

#46

Post by la_barba »

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.

Re: Undervalued Engineering Skills: Writing Well

#47

Post by tombert »

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.

If that's the case then it's kind of mean, isn't it? They know that I'm a grown-up, and are writing to me like a child, effectively talking down to people.

No one is going to give you major adoration for using the word "you" instead of "u", or "are" instead of "r", so I sincerely doubt they're doing it as some sort of humbling thing.

Re: Undervalued Engineering Skills: Writing Well

#49

Post by Crinus »

drewmol wrote: post #16
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…

Curious as I will sometimes find myself annoyed at a similar email... If it said "When are you going to do this?" would that be acceptable?

Yes, i can understand if you are trying to save some SMS space on a phone because the longer the SMS the more you pay, but when writing an email you do not have such limitations.

Re: Undervalued Engineering Skills: Writing Well

#50

Post by namibj »

drewmol wrote: post #16
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…

Curious as I will sometimes find myself annoyed at a similar email... If it said "When are you going to do this?" would that be acceptable?

I sometimes use that when I have a low risk of typos and I am limited in my typing speed. It takes significantly more cognitive effort, and often I can just type if 9ut faster than the other way around.
Post reply on HN