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

71–80 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#71

Post by sokoloff »

C1sc0cat wrote: post #64
mabbo wrote: 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…

The participants had not read the agenda, docs and done their actions before the meeting?

This process is designed to ensure that the docs have been read and have been freshly read. I think of it as moving the time and effort into a defined and nearby time, and it's far from a "waste" of time, IMO.

Re: Undervalued Engineering Skills: Writing Well

#72

Post by Topgamer7 »

funkymike wrote: post #69
mabbo wrote: 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.

Bake it into the meeting.

Re: Undervalued Engineering Skills: Writing Well

#73

Post by munificent »

beat wrote: post #25

I used to be a huge proponent of learning to write well as the most important skill an engineer can learn. Now, I think it's the second most important skill. The most important skill is sales . The key value of writing well, in a workplace environment (or other environments, really) is to convince others to agree with what you're proposing. Convincing people that something they don't initially understand or trust is…

I disagree that this separate from writing as a skill.

I don't think you can characterize any writing as "good" if it fails to persuade the reader to care about the author's message. The audience for writing is humans and the author has to get their message to stick in that human's head. A piece of text that is precise, terse, grammatically correct, and completely uninteresting or persuasive is not writing, it's merely a catalog of facts.

But I agree totally that the "get the person to care" aspect is a fundamental part of writing well that is very often overlooked in technical writing.

Re: Undervalued Engineering Skills: Writing Well

#74

Post by sokoloff »

leesec wrote: post #61
tombert wrote: post #6

I do find it a bit bizarre that the otherwise smart people that I work with, with English as their first language, will often resort to writing emails and documentation like a 14-year-old on AIM. I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers. I'm hardly Jo…

I find it bizarre that most people don't realize writing 'correctly' is just intelligence signaling too. There's no reason for it most of the time. If I can type something faster but still just as clear by typing it less-formally, I will often do so.

"but still just as clear" is a critical qualifier in your sentence. With that stipulated, I agree. When that is absent is when there's an issue.

This is a not a matter of "Never end a sentence on a preposition." "This is the type of errant pedantry up with which I will not put."

Re: Undervalued Engineering Skills: Writing Well

#75

Post by IggleSniggle »

C1sc0cat wrote: post #64
mabbo wrote: 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…

The participants had not read the agenda, docs and done their actions before the meeting?

I had the same initial reaction, but then again...doing it during the meeting, always, ensures that all participants are at least talking about the same thing. I’ve been in meetings where it doesn’t become clear until very late that someone is bullshitting and has not actually read the materials, or read them so lightly that their comments/opinions are not well directed. This is, imho, much worse than making sure everyone is on the same page. Since everyone is presumably going to need to read the docs at some point anyway, incorporating the activity doesn’t really seem like a waste of time to me.

Re: Undervalued Engineering Skills: Writing Well

#76

Post by beat »

la_barba wrote: post #46
beat wrote: post #25

I used to be a huge proponent of learning to write well as the most important skill an engineer can learn. Now, I think it's the second most important skill. The most important skill is sales . The key value of writing well, in a workplace environment (or other environments, really) is to convince others to agree with what you're proposing. Convincing people that something they don't initially understand or trust is…

That sounds like a contrived scenario to me personally. Most programmers simply do the task that their supervisor or manager has assigned to them. Its not like they can refuse to do a task simply because it was worded poorly. They would just ask for further clarification.

Most programmers simply do the tasks assigned to them, because most programmers don't know how to sell!

If you can sell, then you get to decide what you should be working on, convince your manager (and team leads, and other managers, and business teams, and anyone else who might be a stakeholder or shot caller) that it is in their best interest to have you work on the thing you have recommended. Note that this can't be BS... what you're recommending has to be an actual win for them. So, when you've completed the task you sold them on, they see you as a visionary and successful technical leader. The trust that creates will allow you to pick bigger, more ambitious things to work on.

Of course, this assumes that you want to take control over your own work. If you're content just doing what you're told to do, then keep on doing that.

Re: Undervalued Engineering Skills: Writing Well

#77

Post by munificent »

nihil75 wrote: post #39

Why is it undervalued? because you decided it's so? It's extremely valued, and even specified as a requirement for most positions (either explicitly or under "communication skills").

It's undervalued if you observe the amount of deliberate effort most engineers put into improving that skill compared to the benefits they would garner from doing so.

Re: Undervalued Engineering Skills: Writing Well

#78

Post by rgoulter »

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…

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.

Re: Undervalued Engineering Skills: Writing Well

#79

Post by sokoloff »

qznc wrote: post #41
tombert wrote: post #6

I do find it a bit bizarre that the otherwise smart people that I work with, with English as their first language, will often resort to writing emails and documentation like a 14-year-old on AIM. I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers. I'm hardly Jo…

I don't care if you write "you" or "u". I do care a lot about clear definitions in technical writing. For example, someone could mention a "system". What exactly does he mean? Is it synonymous to "the servers" he mentions in the next paragraph? Or is there an important difference? Even worse if people do not even read the text and only look at the diagrams. Hours of meetings could be replaced with minutes of reading.…

And units!

Please both put the units in writing and make sure they're correct! Your network does not run at 100 milli-bits per second. A byte (B) is a lot bigger than a bit (b). Mega (M) is not the same as milli (m). Term contract prices are typical per month or per year, so when you tell me the contract is "only $25K", you haven't told me anything. Tell me it's "$25K/yr" or "$25K/mo" and you've told me something.

Re: Undervalued Engineering Skills: Writing Well

#80

Post by everyone »

I think writing well is a skill that is in very short supply all around, even in writing-focused areas like journalism. A major culprit in this, in my opinion, is how writing is taught in college. It's very common for students to be tasked with writing an essay with a minimum word count. This has been training people into the habit of being unnecessarily wordy and obtuse. What they should do, is give students a higher mark the less words they use to make their point.
Post reply on HN