Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#361

Post by colanderman » Sat, Jun 01, 2019, 5:22 PM UTC

chrisseaton wrote: post #331

colanderman wrote: post #322

Earlier quoted context omitted.

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

This argument doesn't make any sense, because someone who somehow manages to find 'must' ambiguous would also find 'absolute requirement' ambiguous. The RFC doesn't solve the problem, if there is a problem in the first place. If 'absolute requirement' is clear enough as plain English in a normal sentence, without having to capitalise it, then why isn't 'must' clear enough?

You must not see the value in dictionaries, or explanatory text, or examples at all.

Let me rephrase: would you have a problem with RFC 2119 if it defined the terms P0, P1, and P2? If so, why? (That would be a bizarre stance to me.) If not, why do you see it as problematic that they chose the words MUST, SHOULD, and MAY, instead of P0, P1, and P2? After all, there's no logical fault in choosing more memorable names.

I see this problem in code often too. Some people think it's sufficient to give functions and variables English names with "obvious" meanings. Yet however "obvious" the meaning is to you, it can be interpreted differently by different people because English is ambiguous. Such symbol names without comments ascribing them a meaning plain English might as well just be "xyzzy", "qwert", and "l33t". English-named symbols are mnemonic devices, nothing more.

Example: the code base I work on as two commonly-used functions, "findObject" and "getObject". One returns a reference to an object only if already cached; the other fetches it from disk if necessary. Which does which? Does "find" mean to go out and actively "find" the object? Or is it referring to the fact that it only returns the object if it is "found" in cache? After all "get" is a pretty active verb. I guarantee you, whoever named these (and didn't document them!) thought like you, that the meanings were "obvious" and "unambiguous". And I bet they were, to that person, at that time, in that context.

I for one, can never remember whether SHALL is mandatory or not, or whether SHOULD indicates nice-to-have-but-not-mandatory, or purely optional. They're terrible English words to use in a formal specification. But the mere fact that RFC 2119 disambiguates them as formal terms in the context of specifications makes them eminently usable for that purpose.

Re: Undervalued Engineering Skills: Writing Well

#362

Post by AceyMan » Sat, Jun 01, 2019, 5:57 PM UTC

ekianjo wrote: post #338

afarrell wrote: post #282

Earlier quoted context omitted.

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?

Anecdotal evidence: in large corporations good luck finding leaders who can write anything in a clear and concise way. There are some, but by far and large they are exceptions. So much for "write well can propel you to the heights of leadership of a nation", playing politics is definitely the more important predictor than anything else.

Here, here.

FWIW, "Writing Without Bullshit" by Josh Bernoff (Harper Business, 2016) tackles this truth head-on. I liked what I saw when I took a look at my local bookstore and it's gotten excellent user reviews on AMZN.

It'd make a great gift for the PHB manager/director/CEO in your life .

(me: no affiliation, just sharing)

Re: Undervalued Engineering Skills: Writing Well

#363

Post by chrisseaton » Sat, Jun 01, 2019, 6:02 PM UTC

colanderman wrote: post #361

chrisseaton wrote: post #331

Earlier quoted context omitted.

This argument doesn't make any sense, because someone who somehow manages to find 'must' ambiguous would also find 'absolute requirement' ambiguous. The RFC doesn't solve the problem, if there is a problem in the first place. If 'absolute requirement' is clear enough as plain English in a normal sentence, without having to capitalise it, then why isn't 'must' clear enough?

You must not see the value in dictionaries, or explanatory text, or examples at all. Let me rephrase: would you have a problem with RFC 2119 if it defined the terms P0, P1, and P2? If so, why? (That would be a bizarre stance to me.) If not, why do you see it as problematic that they chose the words MUST, SHOULD, and MAY, instead of P0, P1, and P2? After all, there's no logical fault in choosing more memorable names.…

No you're missing my point.

These words already have definitions. You can look them up in a dictionary. Or almost all speakers know them anyway.

Why do we need an RFC, and to write them in capital letters?

What does the RFC add to anything? If you removed the capitalisation and the reference to the RFC then your text means exactly the same thing, as the words already had the same meanings.

> English is ambiguous

Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.

> I for one, can never remember whether SHALL is mandatory or not

What do you think 'shall' means in a normal conversation? How could it mean anything except mandatory? In what normal English context does 'shall' mean optional?

If a normal person tells you that you must submit your expenses before the end of the month do you get confused about whether it's required or not? If they write it in capitals and refer you to the RFC do you suddenly understand now?

Re: Undervalued Engineering Skills: Writing Well

#364

Post by colanderman » Sat, Jun 01, 2019, 7:15 PM UTC

chrisseaton wrote: post #363

colanderman wrote: post #361

Earlier quoted context omitted.

You must not see the value in dictionaries, or explanatory text, or examples at all. Let me rephrase: would you have a problem with RFC 2119 if it defined the terms P0, P1, and P2? If so, why? (That would be a bizarre stance to me.) If not, why do you see it as problematic that they chose the words MUST, SHOULD, and MAY, instead of P0, P1, and P2? After all, there's no logical fault in choosing more memorable names.…

No you're missing my point. These words already have definitions. You can look them up in a dictionary. Or almost all speakers know them anyway. Why do we need an RFC, and to write them in capital letters? What does the RFC add to anything? If you removed the capitalisation and the reference to the RFC then your text means exactly the same thing, as the words already had the same meanings. > English is ambiguous Well…

> Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.

The same way that a dictionary definition clarifies the meaning of a single English word. By using complete sentences to rule out grey areas.

I see no point in furthering this discussion. Your defeatist assertions like the above "there's no possible way to disambiguate English", your refusal to admit that apparent synonyms such as "must" and "shall" might not be perfect synonyms to people other than yourself, and your repeated sarcasm and snark, suggest to me that you do not see the opposite viewpoint as legitimate, and therefore are not amenable to changing your viewpoint.

Re: Undervalued Engineering Skills: Writing Well

#365

Post by microtherion » Sat, Jun 01, 2019, 7:18 PM UTC

rgoulter wrote: post #328

microtherion wrote: post #228

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

Very insightful, thanks for sharing!

Re: Undervalued Engineering Skills: Writing Well

#366

Post by chrisseaton » Sat, Jun 01, 2019, 7:20 PM UTC

colanderman wrote: post #364

chrisseaton wrote: post #363

Earlier quoted context omitted.

No you're missing my point. These words already have definitions. You can look them up in a dictionary. Or almost all speakers know them anyway. Why do we need an RFC, and to write them in capital letters? What does the RFC add to anything? If you removed the capitalisation and the reference to the RFC then your text means exactly the same thing, as the words already had the same meanings. > English is ambiguous Well…

> Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous. The same way that a dictionary definition clarifies the meaning of a single English word. By using complete sentences to rule out grey areas. I see no point in furthering this discussion. Your defeatist assertions like the above "there's no possible way to disambiguate English", yo…

> The same way that a dictionary definition clarifies the meaning of a single English word.

Right, so use the dictionary we already have! Why do we need the RFC?

> "there's no possible way to disambiguate English"

This quote isn't from me. I didn't say that - I don't know where you've got it from.

> your repeated sarcasm and snark

Sarcasm and snark? I don't use those rhetorical devices if I can avoid it. I don't think I've used them in this thread at all! I don't know where you've got the idea that I'm not arguing seriously from. I'm sorry I gave that impression.

My legitimate argument is that nobody is honestly confused by words like must - nobody. The RFC is over-the-top formalism where it's not needed.

Re: Undervalued Engineering Skills: Writing Well

#367

Post by [deleted] » Sat, Jun 01, 2019, 7:35 PM UTC

unfocused828 wrote: post #297

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…

I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety? I genuinely don’t know how to find one. Therapist-shopping is baffling. I ask this as a software engineer who can produce pretty solid writing if…

[deleted]

Re: Undervalued Engineering Skills: Writing Well

#368

Post by bdowling » Sat, Jun 01, 2019, 9:26 PM UTC

unfocused828 wrote: post #297

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…

I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety? I genuinely don’t know how to find one. Therapist-shopping is baffling. I ask this as a software engineer who can produce pretty solid writing if…

Have you considered that you might have ADHD or some other cause for your writing difficulties besides just anxiety? If so, it may help to work with an occupational therapist to come up with specific strategies to work better (e.g., setting up an environment conducive to writing, scheduling time to write, outlining before beginning).

Re: Undervalued Engineering Skills: Writing Well

#369

Post by inflatableDodo » Sun, Jun 02, 2019, 8:39 AM UTC

sixstringtheory wrote: post #254

inflatableDodo wrote: post #26

Writing well? I've had to read engineering drawings for QC in a precision engineering shop working with critical industries. Screw grammar and style being undervalued. You get told to fuck off if you complain about spelling. edit - there is a pathological aversion to updating a drawing, not because of the work, but because of the process. People will do almost anything to avoid having to get an update signed off.

Assuming QC == quality control, I find that attitude highly ironic. Measure twice, cut once. Take the time to write carefully up front and proofread, before you submit it to a lengthy process.

I think a lot of people doing the drawings are either dyslexic, or maybe just do not care. Also, engineering companies don't tend to have proofreaders. I can proofread, but learned quickly that I should not bother proofreading the drawings that came through. All it ever achieved was a torrent of abuse, combined with a flat refusal to even think about getting a new drawing issued.

Re: Undervalued Engineering Skills: Writing Well

#370

Post by samirm » Sun, Jun 02, 2019, 3:30 PM UTC

sokoloff wrote: post #210

samirm wrote: post #160

Earlier quoted context omitted.

I don't see how this would prevent depth of analysis?

How could I do any off-line research into the topic or a specific point in your paper if I've only seen it for the first time in the meeting?

You do it with your laptop in the meeting...