Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#331

Post by chrisseaton » Sat, Jun 01, 2019, 3:40 AM UTC

colanderman wrote: post #322

chrisseaton wrote: post #239

Earlier quoted context omitted.

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 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?

Re: Undervalued Engineering Skills: Writing Well

#332

Post by Wowfunhappy » Sat, Jun 01, 2019, 3:42 AM UTC

TeMPOraL wrote: post #281

EForEndeavour wrote: post #203

Earlier quoted context omitted.

The BLUF is exactly analogous to what the internet hivemind calls the tl;dr (too long; didn't read). I almost always see the tl;dr as the last line of a long post, when really, it makes a lot more sense to lead with it.

Seconded. I always put TL;DR at the beginning if it's meant as an actual summary. I sometimes put a TL;DR at the end, when it's meant as a humorous summary.

It stands for "too long; didn't read." The operative word here is "didn't".

"If you started out trying to read this, but then realized it was too long and just skipped to the end, here is what you missed."

Re: Undervalued Engineering Skills: Writing Well

#333

Post by pjungwir » Sat, Jun 01, 2019, 3:56 AM 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…

I used to help coach college friends in their writing. Often their first drafts would have complicated pretentious sentences that really weren't even parseable as sentences, and first I'd ask them, "What do you mean here?" And then when they'd explain, "Write that down!" Perhaps something like that would work for you, to help take you from a "composing" mindset to a "conversing" mindset. You could even record yourself or use some dictation software. It may even make your writing easier to read.

It might also reassure you that professional writers often say, "There is no writing, only re-writing." The first draft is never the final draft, so you don't have to take it seriously. Just jot down whatever comes into your head. Some people start with an outline, scattered words with arrows connecting them, questions to answer, blank spots, etc., whatever helps to keep you moving forward. Getting started is the hardest part. Keats used to chain himself to his desk to force himself to write something. Sometimes it even helps to set yourself a silly challenge, like randomly open the dictionary ten times to pick ten words you have to include. They don't have to make it into the final draft---but they could. :-)

You might also want to read some books about good writing. Strunk & White is good. Their advice is "keep it simple." Clear and Simple as the Truth is sort of a step past that to a slightly more artful style. Another book I enjoyed was The Artist's Way, which despite the title has a lot about writing.

I don't know anything about professional therapy, and perhaps these suggestions are all way off the mark for you, but I offer them just in case you find them useful. I'm sorry that writing is so painful for you!

Re: Undervalued Engineering Skills: Writing Well

#334

Post by puzzledobserver » Sat, Jun 01, 2019, 4:02 AM UTC

bloopernova wrote: post #184

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'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.…

Is it really wise for design documents to rely on nuances of language? How many of your readers could you reasonably assume have read RFC 2119? How many of your readers could you reasonably assume to be native English speakers? How many native English speakers would be able to comfortably articulate the difference between "shall" and "should"?

And no, not every design document is intended for professionally-licensed engineers, safety-critical applications, or to be used in legal courts. Even when safety is not at stake, writing remains important.

If you find yourself relying on technical and prescriptive descriptions of language use, isn't it perhaps a good idea to think about what exactly you're trying to convey?

Re: Undervalued Engineering Skills: Writing Well

#335

Post by NateEag » Sat, Jun 01, 2019, 4:33 AM UTC

blondin wrote: post #319

pests wrote: post #248

Earlier quoted context omitted.

In the end all writing or speech is about communicating an idea. My opinion is these people have learned it doesn't matter. If an idea can be conveyed in smsesque and still get the point across while being quicker to write, then why not? I have a feeling power/authority/expert status matters here because the listeners will power through unclear communication just to gleam a glimpse of the underlying idea from this id…

exactly! i am reading all these replies and i found them really interesting. i think the same people being annoyed by sms-like writing, would get mad at me not using proper casing with my sentences. at the end of the day, i think it does not matter. i am not writing a book or an article. and when i am texting, i would rather keep it short, sms-like. i would like to understand, truly, why people get mad at such things…

Emoji are a terrible insult to the written word. They're also an affront to imagery.

Standard images, at least, are the same image everywhere. A grid of pixels is a grid of pixels.

Emoji, however, vary from platform to platform, so what you pick may well not be what your reader sees. In some cases that may matter, in others it may not.

Furthermore, some people construct new meanings and usages for emoji that do not align with the actual descriptions from the Unicode standard. You'll only realize this if they tell you, of course. I had one of those moments with my wife a few weeks ago.

I'm still (irrationally) upset that emoji are in Unicode. They're ambiguous, ill-defined, and they are certainly not characters in the multilingual support sense of the word.

Do I use them? Yes, grudgingly, and I hate myself a little bit every time I do it.

Re: Undervalued Engineering Skills: Writing Well

#336

Post by munchbunny » Sat, Jun 01, 2019, 4:37 AM UTC

bloopernova wrote: post #184

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'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 think asking for RFC compliance is asking people to pay too high of an up front effort cost for what you are trying to achieve, unless you really are writing standards and not sketches of features.

What is the problem you're actually trying to solve? People not implementing to spec? That's seldom solved by changes to language, and more often solved by an engineer getting asked to fix an incorrect implementation.

Re: Undervalued Engineering Skills: Writing Well

#337

Post by AlexCoventry » Sat, Jun 01, 2019, 4:46 AM UTC

deathanatos wrote: post #309

wool_gather wrote: post #149

Earlier quoted context omitted.

I've found just declining these no-info meetings to be an effective way to combat the time loss. It's most constructive to send an email alongside saying something like "please share an agenda or materials for this", but that can vary based on context too. And you can even decline after that happens: "Thanks for the details. I'm sorry, but I cannot take the time away from X right now to attend this. Next week may be…

You say that, and it sounds like it ought to work, and yet… I had to do that to a co-worker, and all I got back was "Product Foo". Okay, but what about Product Foo? Blood from a stone, every damn time, and it wears me down.

"I'm sorry, my responsibilities don't leave me any time to discuss Foo in general terms at the moment. If you really you need me to, please raise it with $manager, and we will reprioritize my duties."

Re: Undervalued Engineering Skills: Writing Well

#338

Post by ekianjo » Sat, Jun 01, 2019, 4:52 AM UTC

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?

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.

Re: Undervalued Engineering Skills: Writing Well

#339

Post by Myrmornis » Sat, Jun 01, 2019, 6:34 AM UTC

I agree that writing well is extremely important. However people like to do so much verbally in meetings, that what you write will probably not be read carefully.

Re: Undervalued Engineering Skills: Writing Well

#340

Post by zn44 » Sat, Jun 01, 2019, 7:19 AM UTC

This article comes at a perfect time. As I want to work on my writing skills. I’ve found many recommendations in this thread on how to improve your skills but nothing focusing on technical writing.

Any recommendations for materials specifically for developers?