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

31–40 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#31

Post by asark »

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.

Writing well doesn't mean you're smart, it just means you've put some effort into writing well. It's an exercise in empathy and consideration for one's readers, and crafting tolerable sentences with reasonably-normal usage is just the start of it. Ensuring you're writing something worth reading, with every sentence and every word, is another. "Bullshit written by ignorants" tautologically falls short of that, however fit their writing is otherwise.

Re: Undervalued Engineering Skills: Writing Well

#32

Post by mrmrcoleman »

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] https://vimeo.com/134601419

Re: Undervalued Engineering Skills: Writing Well

#33

Post by beat »

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 learning curves.

Customers often don't understand their own needs very well, so a big part of sales is helping the customer understand their own problems, in order to provide valuable solutions.

The engineer who can really dig into requirements, really get to understand the customer and help the customer understand their own needs, and then offers a working solution, with clearly stated benefits and clearly stated costs, will do far better.

Re: Undervalued Engineering Skills: Writing Well

#34

Post by aresant »

In a past life I helped optimize >$1b of online transactions as a CRO professional and learning to objectively "write well" could be quantified in two ways:

1) Message Density - there's a great quote attributed to Mark Twain that nails this "If I'd had more time I would have written you a shorter letter".

In practice Jeff Bezo's push to making executives build "4 page memos" for meetings outlines this idea clearly: "the reason writing a good 4 page memo is harder than "writing" a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related"(1)

2) Message Accessibility - Making your message broadly accessible is a good forcing function to writing clearly. An easy "hack" in this department is to utilize the "gunning fog index"(2) which is a structured way to estimate "the years of formal education a person needs to understand the text on the first reading" and there are many tools online that can spit out a score.

(1) https://slab.com/blog/jeff-bezos-writing-management-strategy...

(2) https://en.wikipedia.org/wiki/Gunning_fog_index

Re: Undervalued Engineering Skills: Writing Well

#35

Post by asark »

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.

Yup. Anti-signal-signals are a thing. "I don't want or need to care how hard it is for you to understand me, so I'm not going to give any thought or effort to making it easier for you" is certainly a kind of signal.

Re: Undervalued Engineering Skills: Writing Well

#36

Post by ErrantX »

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.

I think, in my experience, that there is a middle way which Ive seen the very best use (and try to follow). Fundamentally it is not about how much you write but how well you communicate.

There is a difference in people that rattle off sms-style one liners every time, and those who know they only need one line to communicate fully.

My experience is; the former style almost always leads to an email chain where one party steadily extracts information from the other, like pulling teeth

Re: Undervalued Engineering Skills: Writing Well

#37

Post by hbarka »

In the US university system there are undergraduate requirements called distributional or general education requirements. The breadth of the courses cover humanities and arts, social sciences, and other classes under a Liberal Arts category. I wonder if there are similar requirements in other countries. Does an undergrad degree, say in India, have an apples-to-apples equivalent to an undergrad in the US with respect to the distributional requirement.

Re: Undervalued Engineering Skills: Writing Well

#38

Post by pmontra »

tombert wrote: post #17
enriquto wrote: post #14

Earlier quoted context omitted.

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…

I agree. We can write smsque in a slack channel and "its ok", but it's not OK to write like that in a document sent to customers, in a wiki that explains how a piece of software works and will stay there for years or in an email aimed at winning an argument. Those would be detrimental to the company and to the developer.

Re: Undervalued Engineering Skills: Writing Well

#40

Post by dsfyu404ed »

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…

A good tutorial is it own documentation and good documentation is its own tutorial.

I've yet to find anything that packs a bigger punch than screenshots annotated with MS paint paired with concise description.

Post reply on HN