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

11–20 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#11

Post by Ixiaus »

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…

And then specify the design doc with TLA+!

I agree with your point and I also think English is imprecise. It's great for socializing and flushing out ideas but it can also give one a false sense of confidence.

Re: Undervalued Engineering Skills: Writing Well

#12

Post by tombert »

sokoloff wrote: post #10
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…

“Writing is nature's way of telling us how lousy our thinking is.” ― Leslie Lamport

I love that quote, but Lamport actually says in the Specifying Systems book that he got it from Dick Guindon.

I mention this purely in the interest of pedantry.

Re: Undervalued Engineering Skills: Writing Well

#13

Post by Ixiaus »

Ixiaus wrote: post #11
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…

And then specify the design doc with TLA+! I agree with your point and I also think English is imprecise. It's great for socializing and flushing out ideas but it can also give one a false sense of confidence.

Really there's a general point here I think: up front, careful reasoning (which should eventually excogitation in English or math or code) not only helps prevent mistakes but it also produces documentation and reasoning collateral.

Re: Undervalued Engineering Skills: Writing Well

#14

Post by enriquto »

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 used to think like that (being the kid that wrote well in school). But now I'm not so sure anymore...

Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.

Re: Undervalued Engineering Skills: Writing Well

#15

Post by sanderjd »

adamnemecek wrote: post #2

It's hardly undervalued. Another one mentioned too much is "empathy". I feel like these are such softball answers, as no one will say no, this is bullshit.

It definitely is undervalued. There is very direct evidence of this: technical writing plays exactly zero role in the hiring process. That process tends to be more than 90% or so focused on coding, and the other 10% is not writing, it is some combination of credentials, knowledge of current trends in the field, ability to seem like you would fit in at the company, and drawing system diagrams. But technical writing - in code documentation, design documents, task definitions, bug reports, emails, and chats - is often the greater portion of my job in a week, and it is pretty much always the more important part.

I agree a bit more that "empathy" is sometimes used in a BS-y way, but at its core it just means seeing things from more than only your own perspective. Which is definitely an important thing to do. I would probably agree that it is undervalued, though there seems to be more awareness or at least lip service to it than to the importance of writing.

Re: Undervalued Engineering Skills: Writing Well

#16

Post by drewmol »

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?

Re: Undervalued Engineering Skills: Writing Well

#17

Post by tombert »

enriquto wrote: post #14
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 used to think like that (being the kid that wrote well in school). But now I'm not so sure anymore... Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.

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 give the optics of someone who is smart. Is that the way it should be? Probably not, but I don't make the rules.

Re: Undervalued Engineering Skills: Writing Well

#18

Post by tombert »

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, that is fine. I'm obviously not asking for someone to write the next Moby Dick when sending me an email asking for a status update. A short and simple message is totally fine, I just would be prefer that it be (mostly) grammatically correct.

Re: Undervalued Engineering Skills: Writing Well

#20

Post by sanderjd »

stronglikedan wrote: post #3
adamnemecek wrote: post #2

It's hardly undervalued. Another one mentioned too much is "empathy". I feel like these are such softball answers, as no one will say no, this is bullshit.

It's definitely undervalued by engineers themselves. I.e., the majority don't seem to treat this skill as a priority in their professional development. However, it's definitely not undervalued by the companies that hire them. Especially as they progress through their careers, where they will experience a glass-ceiling affect if they have not sharpened that skill. EDIT: Fixed stupid autocorrect error (thanks sokoloff)…

I think this is true inside a company, but it is another example of how weird our hiring techniques are. Writing plays basically no part in the hiring process. So for those engineers who have progressed by sharpening that skill, it is jarring to find that the barrier to their next job takes absolutely no account of it. You can spend years impacting or entirely setting the technical direction of a project or entire company through your writing (and verbal communication as well), and then find that all you're asked during your interview for your next job is to solve some made up problem using code on a whiteboard. It's bizarre.
Post reply on HN