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

321–330 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#321

Post by lukeHeuer »

mnorton wrote: post #24

I have kept around and distributed multiple copies of The Elements of Style, by Strunk and White, for the past few years (lots of revisions of this out there, 4th might be most recent iirc). It's like a 9$ book and the guidance is priceless. https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...

Most of the guidance is very outdated. It's likely to confuse more than clarify unless you've taken the time to study modern resources. I prefer Bryan Garner's work, like his usage guides.

There is a great episode of Lexicon Valley where the dustier advice from The Elements of Style is called out: https://podcasts.apple.com/ca/podcast/against-strunk-white/i...

Re: Undervalued Engineering Skills: Writing Well

#322

Post by colanderman »

chrisseaton wrote: post #239
walshemj wrote: post #230

Earlier quoted context omitted.

You are assuming that everyone working with the document is a native English speaker and / or has worked to a standards based development system. Even so back in the day ICL managed to ignore a counter MUST start from Zero in implementing an X.400 stack - and you wonder why the uk No longer has a mainframe supplier.

If people can't understand the simple word 'must' how will they understand the more complicated words that RFC 7322 uses to define it?

That's… not the point of RFC 2119. The point is to specify specific words used to indicate various levels of adherence to a standard. Maybe "must" clearly indicates a strong requirement to you (as opposed to an optional requirement). Does "should"? How about "shall"? The English interpretation of these words contains shades of grey, and different people will interpret them differently, sometimes even depending on context.

Why invite such ambiguity? It leads to problems, when the designer writes "shall" and the implementer takes it as a suggestion, or the designer writes "should" and the implementer sinks months trying to satisfy what turns out to be a requirement the implementer intended as optional in light of unknowns.

Clarifying terms eases communication. RFC 2119 isn't about defining basic words of the English language for imbeciles. It's about selecting words to indicate precise levels of compliance. They could have equally named the levels P0, P1, and P2. Instead they chose MUST, SHOULD, and MAY to indicate the same, while reading more easily as part of a sentence.

Re: Undervalued Engineering Skills: Writing Well

#323

Post by sonnyblarney »

thrower123 wrote: post #300
JamesBarney wrote: post #283

Earlier quoted context omitted.

In the sense I've never seen any interview require a writing sample from a dev.

You have to write at least a few coherent, error-free paragraphs in your resume typically. It's something of a good filter to toss out people that either can't, or can't be bothered to, write clearly for that small sample.

People generally don't read prose in technical resumes, moreover, I'd never hold it against a candidate because they're nudged into writing in a highly summarized, notation style. Unless there were blatant issues with language, and then I'd be super concerned about blowing off an 'english as a second language candidate'. About 1/2 of devs it seems are from 'somewhere else' and we can't expect them to have world class technical chops and perfect fluency.

Re: Undervalued Engineering Skills: Writing Well

#324

Post by sonnyblarney »

chrisseaton wrote: post #204
bloopernova wrote: post #184

Earlier quoted context omitted.

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.…

I don’t think the key to effective writing is following a bunch of standards.

It's the key to 'effective communication' in particular environments.

Words have meaning, and because language is vague, we help it a little by pinning down the meaning of certain words: this is for clarity, it's not a constraint.

Re: Undervalued Engineering Skills: Writing Well

#325

Post by colanderman »

catherd wrote: post #313
cosmodisk wrote: post #258

Earlier quoted context omitted.

I'm not a native English speaker. Half of the team I manage are native English speakers,the rest are not. The recent project they did on communication templates was checked by the French colleague,while I no longer forward some of the files to English native speakers because they can't form sentences thst are clear enough to understand by others. It is not easy for a lot of people.

I work with a team that spans native speaker to barely able to form English sentences, and communicating clearly in a mixed audience like that is really a completely separate skill from native language use. For the ones with minimal English it's often clearer to use phrasing that a native speaker would say is obviously wrong, but matches their native language patterns. Or use simpler but not-quite-appropriate words.…

I find that awareness and avoidance of idioms is much easier once one has learned (well) a second language. I am fluent in Esperanto, and somewhat subconsciously translate much of what I write as I am writing it. It leads me to choose simpler words and grammatical constructs, and to avoid circumlocutions and especially idioms.

Re: Undervalued Engineering Skills: Writing Well

#326

Post by chii »

stcredzero wrote: post #223
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…

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. It's the same phenomenon of "rubber duck" software engineering, or when you start composing the very rigorous email asking a question of another programmer, then find you've answered your own que…

>> it forces you to reason things through properly

the same could be said for using static types to express the thoughts and formal reasoning rather than english though.

Re: Undervalued Engineering Skills: Writing Well

#327

Post by philwelch »

afarrell wrote: post #282
lpolovets wrote: post #188

Writing well is an undervalued skill in life, not just in engineering. When you work on a team of peers with similar skills in your field, whether that field is engineering or something else, being able to write well and communicate well become strong differentiators. FWIW, I'm pretty sure that writing (reasonably) well online is what got me a job in venture capital after ten years as an engineer. David Perell (host…

In what sense is it under -valued? There is a fabulously popular musical about how the ability to write well can propel you to the heights of leadership of a nation. In my experience, people believe that the ability to write well is key to professional success. Where are the people who believe that writing is not a valuable skill?

Largely in how companies seem to store and transmit information either verbally or via PowerPoint rather than the written word.

Re: Undervalued Engineering Skills: Writing Well

#328

Post by rgoulter »

microtherion wrote: post #228
rgoulter wrote: post #78

Earlier quoted context omitted.

I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status. This sounds like a good piece of advice to keep in mind. It's nicer for the reader to not have to wait till the end to get what's going on.

> I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status. I agree, but maybe that style of writing has evolved for good reasons? In engineering, it seems to be a common personality trait that when presented with conclusions first, we tend to formulate reasons contradicting the conclusions, and then dig in on those reasons, to the detr…

I really love this blogpost which discusses these two personalities, in the context of "corrections from strangers on Twitter". Some see corrections as "sharing information"; others see making corrections as asserting status/dominance which disrupts social harmony. https://status451.com/2016/01/06/splain-it-to-me/

Re: Undervalued Engineering Skills: Writing Well

#330

Post by pugworthy »

ianmcgowan wrote: post #196
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…

It's about emails, but I like this article[0] about how topics are covered in the military (where I imagine clear communication is important). "Military professionals lead their emails with a short, staccato statement known as the BLUF (Bottom Line Up Front). It declares the purpose of the email and action required.". I find this helpful.. [0] https://hbr.org/2016/11/how-to-write-email-with-military-pre...

I have never understood why people put the TL;DR (I assume civ equivalent to BLUF) at the end. I don't want it at the end, I want it at the beginning!
Post reply on HN