Live data from Hacker News

Undervalued Engineering Skills: Writing Well

blog.pragmaticengineer.com

201–210 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#201
post #180

This resonates with me. My writing is clear and concise, I'm proud of it, and it pays off because I can communicate effectively. I'm not sure I agree with the "undervalued", in so far that I see a _lot_ of people who are not able to write clearly, and they get ahead and along just fine. Many executives who I worked with wrote terrible emails (sometimes they leave out the negation, so I'm guessing whether they mean X…

I wonder if they have a junior person that does/did the writing for them. Reminds me of a story about fighter pilots from World War 2. Some of the best fighter pilot aces had, at best, average vision. Their coping strategy for this was to find pilots who weren't as good at dogfighting but had excellent vision as wingmen. Both parties benefited since the better pilot could spot enemy planes earlier and the lesser pilo…

I recently got to ride in the co-pilot seat of our company plane and it was a neat experience to see everything and listen to the radio chatter and the view was amazing to watch the sun rise and the moon set at the same time.

He showed me how as a fighter pilot he was trained to spot other aircraft.

When one would show up on the radar he would point and be like see that plane over there? I could never see it until we were very close and I have great vision and no glasses.

After a few times of this game he then said, "Now when you are looking for another aircraft you don't focus on where it is, scan your eyes left to right horizontally".

Now I was able to pick out the what seemed like 1-2 pixel dot in the distance by not trying to focus on the dot but look at everything else and your brain somehow figures out the anomalous pixel/dark spot against the horizon.

It reminded me a lot of when I was a kid bird hunting how my dad would try to point at the partridge and it was the same game. You try to focus directly at them and it was hard to see them in the brush, but scanning your eyes back and forth helps make them pop out and be visible.

Re: Undervalued Engineering Skills: Writing Well

#202
post #115
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…

Please no. Instead of a clear script, the developer now has first has to wade through word diarrhea to extract meaning. > 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 features, so as not to get into trouble with a rarely used tool that proves buggy with an important customer. I said, and so be it." This could have been replaced…

You do have a point but still let's look at it another way.

It's a ticket. That means that at best it's boring and mundane. The writer knows this and is trying to convince you, to sell you, on spending some time thinking about it. Granted, you should do that anyways but First test new features before sending to customer doesn't really convince you to do that. If your text was enough then maybe it should have been a check box and saved everyone some time.

All that said, there is a time and place for humor. Maybe this was it and maybe it wasn't. Dunno. Audience matters; timing matters; context matters.

Re: Undervalued Engineering Skills: Writing Well

#203

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

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.

Re: Undervalued Engineering Skills: Writing Well

#204
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 don’t think the key to effective writing is following a bunch of standards.

Re: Undervalued Engineering Skills: Writing Well

#206
post #27

Amazon is obsessive about this stuff. I'm surprised the article never mentions it. There are internal classes offered on writing better documents (and it's a great class). There's videos, guides, documents, everything. Writing well at Amazon is key to a successful career here. Got a project idea? Write a very good 1-pager explaining it and you've got a much higher chance of it actually happening. Want to share a desi…

> I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting. I wish this could happen where I am. No one wants to bother reading anything ahead of the meeting to be prepared for a discussion. Then the same people don't have the patience to let the group review the material during the meeting before starting the discussion.

This is exactly the point of the silent reading time. Stop lying to yourself and others by saying you'll read ahead. You won't. No one will. Or worse, everyone but one person will and he'll have "skimmed it" and then ask questions that are on page 2, wasting everyone's time.

If you want to bring this to wherever you work, I encourage it. All you need to do is lead the meeting yourself with a strong, assertive voice. Tell them this is what we're doing. When someone inevitably complains just ask them to please wait to ask questions until everyone is done.

Re: Undervalued Engineering Skills: Writing Well

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

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?

Re: Undervalued Engineering Skills: Writing Well

#208

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.

Standards like grammer?

Re: Undervalued Engineering Skills: Writing Well

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

Without knowing why you want the RFC 2119 language adopted within your organization, I can say that although it's very important that everyone use the same words to refer to the same things, I would be careful when applying rigorous definitions to those keywords.

Are you writing standards for networking, where there could be multiple implementers and you want to be clear to everyone what their implementation has to do? What value do the definitions add? Do people ask questions or have disagreements without the rigorous definitions?

Re: Undervalued Engineering Skills: Writing Well

#210
post #160

Earlier quoted context omitted.

I like this idea on the surface. The flipside though is that if everyone's reading the doc for the first time right before discussion, it doesn't allow for much depth of analysis. Do you also send the materials out beforehand?

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?
Post reply on HN