Undervalued Engineering Skills: Writing Well • Hacker News Board

Re: Undervalued Engineering Skills: Writing Well

#181

Post by abhishekjha » Fri, May 31, 2019, 5:57 PM UTC

rgoulter wrote: post #78

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.

People who design things, how do they make sure that what they are proposing is doable because we won’t know until a group of engineers finish the project and it goes into maintenance?

Re: Undervalued Engineering Skills: Writing Well

#182

Post by dmreedy » Fri, May 31, 2019, 5:57 PM UTC

tombert wrote: post #12

sokoloff wrote: post #10

Earlier quoted context omitted.

“Writing is nature's way of telling us how lousy our thinking is.” ― Leslie Lamport

I love that quote, but Lamport actually says in the Specifying Systems book that he got it from Dick Guindon. I mention this purely in the interest of pedantry.

I had a professor who gave me another favorite quote of mine: "It's worth being pedantic at least twice in your life"

I think the ideas are related.

Re: Undervalued Engineering Skills: Writing Well

#183

Post by allenu » Fri, May 31, 2019, 5:58 PM UTC

abhishekjha wrote: post #173

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…

>Writing a couple of pages of design docs or an Amazon-style 6 pager While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself. I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.

I'm not the poster you're responding to, but for me in my career, I originally tried to design things in more detail up front and write a lot about how it would work.

After many years in the industry, I've actually found that it's better to quickly prototype the various "big pieces" of whatever it is you are designing and learn the constraints of the space you are in first. (You're never going to get everything right with that first attempt at a design.) You can write documents up front explaining what you think your code is going to do, but I would actually not recommend going into too much detail because you only really learn about the problem space you are in by doing.

In terms of a document, keep the initial design light and explain your assumptions, what the technical constraints you face are and how you plan to mitigate them. This is mostly to share out with other people to see if they have concerns about the approach and if they have ideas to help with the process.

Re: Undervalued Engineering Skills: Writing Well

#184

Post by bloopernova » Fri, May 31, 2019, 5:59 PM UTC

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.

It's like they don't want to be pinned down to an exact meaning in design documents! And don't even think about trying to "force" people to use a style guide like RFC 7322, or even an authoritative list of initialisms, acronyms, and abbreviations.

Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken".

This has already gotten too rant-y but it burns my butt so much! So much wasted effort!

Re: Undervalued Engineering Skills: Writing Well

#185

Post by beat » Fri, May 31, 2019, 6:02 PM UTC

munificent wrote: post #73

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

They're both important. The question is, which is more important? Well, what are we measuring? Success in goals. And which is more likely to achieve goals... good writing with poor sales, or good sales with poor writing? I'd argue the latter, for a variety of reasons.

Re: Undervalued Engineering Skills: Writing Well

#186

Post by charliepark » Fri, May 31, 2019, 6:04 PM UTC

turingbike wrote: post #139

aresant wrote: post #34

In a past life I helped optimize >$1b of online transactions as a CRO professional and learning to objectively "write well" could be quantified in two ways: 1) Message Density - there's a great quote attributed to Mark Twain that nails this "If I'd had more time I would have written you a shorter letter". In practice Jeff Bezo's push to making executives build "4 page memos" for meetings outlines this idea clearly: "…

Surprisingly, there are a lot of good tips in the US Gov's Plain Language Guidelines https://www.plainlanguage.gov/guidelines/

That's an excellent resource. Thanks for sharing it.

Re: Undervalued Engineering Skills: Writing Well

#187

Post by mason55 » Fri, May 31, 2019, 6:04 PM UTC

abhishekjha wrote: post #173

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…

>Writing a couple of pages of design docs or an Amazon-style 6 pager While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself. I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.

Start off by writing down a clear goal of what you're trying to accomplish. This is pretty much the first thing I do when I write any document in fact.

Then figure out what the requirements are that help you meet your goal and write those down.

Once you have a goal and a set of requirements the design is usually pretty easy.

Re: Undervalued Engineering Skills: Writing Well

#188

Post by lpolovets » Fri, May 31, 2019, 6:04 PM UTC

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 of the North Star Podcast) has been tweeting a lot of good things about the value of writing + writing tips:

- https://twitter.com/david_perell/status/1127348174404890625

- https://twitter.com/david_perell/status/1124002449646395392

- https://twitter.com/david_perell/status/1116485842615377921

Re: Undervalued Engineering Skills: Writing Well

#189

Post by kstenerud » Fri, May 31, 2019, 6:05 PM UTC

abhishekjha wrote: post #173

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…

>Writing a couple of pages of design docs or an Amazon-style 6 pager While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself. I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.

It's a lot of writing and rewriting. I usually start off putting everything I think I want in the spec into a text document without worrying too much about logical consistency, then leave it overnight, add more things, leave it overnight, reshape, etc. It's important to take a long break after hitting a stopping point so that you gain some perspective. It's also good to solicit comments from your network, although that tends to be as difficult as finding code reviewers, so YMMV.

You should also write a reference implementation, because actually implementing something will expose a lot of problems in your assumptions, and it will give other implementers something to test against.

Generally, it's 3-6 months from inception to release of a smaller spec if you want it to be solid.

Actually, you could follow along with a couple of specs I wrote since I have a git history of them:

https://github.com/kstenerud/streamux/commits/master?after=7...

https://github.com/kstenerud/concise-encoding/commits/master...

Re: Undervalued Engineering Skills: Writing Well

#190

Post by mwfunk » Fri, May 31, 2019, 6:05 PM UTC

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…

This is so true. It's like the old truism about how the way to really truly learn something is to have to explain it to someone else. Literally just going through the process of articulating something, just putting it into words, is an amazing tool for revealing all of the missing pieces and inconsistencies that would otherwise be implicit.

Until you put something into words, one way or another, then it's just a fuzzy blob of assumptions and halfway articulated thoughts. The better someone is at writing, the better they're able to articulate their thoughts, even if it's just to themselves.