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

271–280 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#271

Post by ithkuil »

tomfern wrote: post #175
sokoloff wrote: post #10

Earlier quoted context omitted.

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

I'm stealing that quote, it's so good. I'm always surprised how ideas that sounded wonderful in my head turn into garbage when written down.

An actual quote from Lamport: "mathematics is nature's way to show you how lousy your writing is".

It's layered on top of a quote of Guindon he uses in a book about TLA+ in order to make a point for using math to formally specify systems

Re: Undervalued Engineering Skills: Writing Well

#272

Post by frequentnapper »

lpolovets wrote: post #268
ordinaryradical wrote: post #242

Earlier quoted context omitted.

I'm curious about your experience. How do you think your writing translated into value in the eyes of the VC world? Or was it that you'd built a platform online first through your writing and then they solicited you? In my experience my ability here has always been valued after the fact; I have the strong impression that few companies value writing, even as a secondary skill, or see it as a differentiator.

A few positive experiences I've had related to writing: 1) I used to write a lot on Quora. Being an engineer who can write made my future VC partners believe that I could do more than engineering. I'm pretty sure that building a decent readership base on Quora is what put me on my partners' radar in the first place. 2) Writing on my blog/Twitter/etc has helped put my name and my fund's name on more people's radars an…

How did you transition from Engineer to VC if you don't mind me asking?

Re: Undervalued Engineering Skills: Writing Well

#273

Post by mannykannot »

technofiend wrote: post #262
chrisseaton wrote: post #204

Earlier quoted context omitted.

I don’t think the key to effective writing is following a bunch of standards.

>I don’t think the key to effective writing is following a bunch of standards. Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!

That is how you get compliant language; whether it is effective language depends on what it says.

Re: Undervalued Engineering Skills: Writing Well

#274

Post by allenu »

mannykannot wrote: post #270
zwkrt wrote: post #227

Earlier quoted context omitted.

+1 to prototyping. Having 100 lines of python that does 20% of what you want your full component should do is probably more useful than a 10000 word document outlining 95% of what your component should do. You can lie to yourself in writing but not in code. That being said, documenting in horrendous detail your actual requirements and your assumptions about the state of the world is more useful than either of the abo…

> You can lie to yourself in writing but not in code. You can certainly fool yourself in code, and think you have the solution, or part of it, when, in fact, you do not. If this was not the case, prototyping would be meaningless, as you could only write correct solutions. I would advise abhishekjha to try thinking one or two steps ahead before starting to write the corresponding code, and to pay particular attention…

This is a good point. Some of the techniques that I employ today (prototyping at a large scale) are ones that I can employ simply because I have experience and can see ahead to what potential problems there are in various designs. These things aren't obvious to a junior developer and letting them get too far with a prototype can be dangerous.

Re: Undervalued Engineering Skills: Writing Well

#275

Post by briandear »

technofiend wrote: post #262
chrisseaton wrote: post #204

Earlier quoted context omitted.

I don’t think the key to effective writing is following a bunch of standards.

>I don’t think the key to effective writing is following a bunch of standards. Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!

It depends on what you are writing. Also, there is a question of readability. A document written in legalese is certainly “accurate,” but that doesn’t make it comprehensible. Writing with clarity isn’t about following a standard, it’s about using language in such a way that the consumer of that language understands the message. If documents were written following like the RFC, they’d be incredibly tedious to read. English isn’t a computer language, there is a such thing as context, tone, and diction. Of course if you are actually writing a legal document or standards document, certainly use that idiom.

Re: Undervalued Engineering Skills: Writing Well

#276

Post by [deleted] »

briandear wrote: post #275
technofiend wrote: post #262

Earlier quoted context omitted.

>I don’t think the key to effective writing is following a bunch of standards. Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!

It depends on what you are writing. Also, there is a question of readability. A document written in legalese is certainly “accurate,” but that doesn’t make it comprehensible. Writing with clarity isn’t about following a standard, it’s about using language in such a way that the consumer of that language understands the message. If documents were written following like the RFC, they’d be incredibly tedious to read. En…

[deleted]

Re: Undervalued Engineering Skills: Writing Well

#277

Post by shados »

Maro wrote: 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'm not sure I agree with the "undervalued"

Agreed. Sometimes its even the other way around. You could be an awful engineer from a technical angle, but if you can write good blog post and shiny docs, the powers that be (those who don't look at the code) will think you're awesome.

Still, the skill is insanely valuable. As someone who's not a native english speaker/writer, I can manage, but it takes me 5 times as long to do something less than half as good as my peers, yet I always find myself needing to write a new page of doc, a wiki/blog post, etc. If I was better at it, I'd be much, much more successful.

Re: Undervalued Engineering Skills: Writing Well

#278

Post by jboy55 »

Maro wrote: 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…

>Sometimes the Amazon protocol comes up (before a meeting, the organizer submits the topic in writing, everybody has to read it before), and I always cringe - in my experience most people just can't write a clear 2 page document [or can't be bothered]. I would love it tough.

At Amazon the protocol is to read during the start of the meeting. Typically this can be the first 30 mins of a 60 min meeting.

Re: Undervalued Engineering Skills: Writing Well

#279

Post by TheOtherHobbes »

rootusrootus wrote: post #138
sixstringtheory wrote: post #83

Earlier quoted context omitted.

The signal I get from that is arrogance, then. Also, in an industry where “fake it till you make it” is the rallying cry, one shouldn’t appear dumb, lest one actually becomes dumb (at least in the eyes of their colleagues/superiors/reports/clients).

Exactly what came to my mind as well. A lack of care when you write can signal that you do not know how to write well, or it can signal that you don't care to write well. Neither of these are signals I want to send, both harm my reputation.

It can also be a signal that you're too busy to write well in that context.

There are two elements to writing well. One is the efficient communication of content. The other is communication of social register, relative status, and power relationships.

Hitting the right social register is an impedance matching problem that depends on the target audience.

If you go too high you risk sounding snobby, pretentious, and condescending. If you go too low you won't be credible.

People often assume this means that if you lard your verbiage with orotund circumlocutions and vague implications you'll be hitting those high register top notes.

But in fact social register doesn't map neatly to grammar/reading age/vocab.

SMSspeak in an email can - ironically - hit too high a social register because you're implying you don't have time to write a more detailed and conversational response, and you're not making the conversation a priority.

This is orthogonal to any actionable message content.

Re: Undervalued Engineering Skills: Writing Well

#280

Post by TeMPOraL »

JoshTriplett wrote: post #235
bloopernova wrote: post #184

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

When you say "must" with the weight of RFC 2119, you need to consider the "or what?". If you're writing a standard, what force does it carry? Is there a certification? Is it a marketing issue? Will other implementations put the bad implementation on a blocklist? Will they actually fail to interoperate in practice? Or can someone get away with violating the "must"?

For in-house design documents: or you're not a team player. You've done a bad job. This will screw up something, somewhere, at some point, costing people time and money.
Post reply on HN