Live data from Hacker News

Undervalued Engineering Skills: Writing Well

blog.pragmaticengineer.com

371–380 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#371
post #160

Earlier quoted context omitted.

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

Generally people need some time to ponder new input in order to grasp edge cases, work through implications, identify unspoken assumptions, and so on. Some extraverted folks are happy to "think out loud" in a group, but even then it's too easy for a conversation to move quickly past a particular point that deserves more time.

I agree that needing time for analysis is important, but what's preventing you from working through all of this during the meeting?

Re: Undervalued Engineering Skills: Writing Well

#372
post #370

Earlier quoted context omitted.

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

That imposes two problems: that I am limited to about 15 minutes of research time (limiting depth and basically eliminating "phone a friend" consultations) and it requires that one permits laptops into the meeting.

Nevertheless, I'm a supporter of the approach and have introduced it into the most important review meetings that we hold in my group. (We do bar laptops and other electronics, other than video conferencing equipment.) Results after 18 months seem quite positive on balance.

Re: Undervalued Engineering Skills: Writing Well

#373
post #52

Writing well can have several meanings. I've found that hilarious bug tickets are much better received and treated than dry ones. Maybe because they get many eyeballs (of the sort that makes all bug shallow). Here is one of the first ticket I wrote in my still current company: Then God appeared to wazoox and told him: "You will not spread your software on the face of the world without properly testing the new feature…

This isn't a bug ticket, though, it's a complaint that people didn't write unit tests. Humor works better when genuinely lighthearted and not trying to slip through some criticism. Criticism probably works better when not disguised as a parable inside a bug ticket.

Re: Undervalued Engineering Skills: Writing Well

#374
post #358

I totally disagree with this claim, because, it is discriminating, narrow-minded, shortsighted and subjective. Writing is only a way to convey information, there a many other ways to do it, and there surely will be other ways. The current system favors people who know how to write in English, but it doesn't mean it's fair nor right. A language that may work for you may not work for others, therefore, "well" is not ob…

> Writing is only a way to convey information, there a many other ways to do it, and there surely will be other ways.

It's the best way of conveying information, especially in a business setting. It's accessible, portable, can be as detailed and nuanced as needed, you can copy it, you can reference it later, you don't need a proprietary solution to use it. In fact, you don't even need a computer for it. All other methods of conveying information in a business setting that I can think of (face-to-face communication, video and audio conferences, Power Point presentations, chat apps, symbols, source code) don't meet all of the above criteria.

> The current system favors people who know how to write in English

Now this is discriminating and narrow-minded. Nothing stops a German company from writing well in German - if that's their main language.

I'm curious which system you think is more fair and objective.

> A language that may work for you may not work for others

This could be generalized as "a solution that may work for you may not work for others". And that's ok. An organization can have its own culture. A part of this culture might be writing well, but also agile, open floor plan, working remotely, or afternoon mimosas. It's ok to disagree with the culture of a particular company and not be a good fit. You are free to prefer companies that don't emphasize good writing skills - which I suspect are the majority.

Re: Undervalued Engineering Skills: Writing Well

#375

Earlier quoted context omitted.

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

The RFC is far more useful in dealing with the word "should". It is used in the standards to mean something that is optional but strongly recommended ("there may exist valid reasons in particular circumstances to ignore a particular item"), whereas in english the first definition that comes up is "used to indicate obligation, duty, or correctness".

To me it seems that there could easily be confusion between these two interpretations.

Re: Undervalued Engineering Skills: Writing Well

#376

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

Maybe your colleagues perceive that they are being asked to study a bunch of off-topic material. Is reading RFC 2119 really the most productive use of their time?

https://tools.ietf.org/html/rfc2119 is 664 words, including links, author's contact info, headers/footers, etc.

Also it's basically "what that word means in English".

I don't think it takes that long to study.

Re: Undervalued Engineering Skills: Writing Well

#377
post #326

Earlier quoted context omitted.

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.

Static types are only one part of reasoning through things properly. Rubber ducking or composing that question to a colleague forces you to think of the entire logic and structure around it, etc. Types won't fix that.

Re: Undervalued Engineering Skills: Writing Well

#378

Earlier quoted context omitted.

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

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

Interesting. I often encounter the problem at other the end of the spectrum: People who are used to verbal communication, which often results in rather scarce writing that resembles snippets of a verbal conversation rather than a cohesive thought and therefore lacks to details to properly understand meaning and intention.

Usually that kind of writing requires a lengthy series of follow up questions to learn anything meaningful about the original idea of the author. Conciseness is onyl valuable if it doesn't sacrifice substance and meaningful content.

Re: Undervalued Engineering Skills: Writing Well

#379
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...

There's definitely stuff in there that is dusty for sure. Thanks for this.
Post reply on HN