23 ms·

Undervalued Engineering Skills: Writing Well

• adamnemecek 7y ago
  It's hardly undervalued. Another one mentioned too much is "empathy". I feel like these are such softball answers, as no one will say no, this is bullshit.
  • stronglikedan 7y ago
    It's definitely undervalued by engineers themselves. I.e., the majority don't seem to treat this skill as a priority in their professional development. However, it's definitely not undervalued by the companies that hire them. Especially as they progress through their careers, where they will experience a glass-ceiling affect if they have not sharpened that skill. EDIT: Fixed stupid autocorrect error (thanks sokoloff). I wish browser inputs had grammar hints as well as spelling correction.
    • sokoloff 7y ago
      Though I was a "pretty good or better" software engineer, it's almost surely the case that I've made more career gains from English-language writing than code-writing during my career. (Normally I'd let this pass without comment, but because of the specific topic of this comment chain, you mean "glass-ceiling effect" not "affect" there.)
    • sanderjd 7y ago
      I think this is true inside a company, but it is another example of how weird our hiring techniques are. Writing plays basically no part in the hiring process. So for those engineers who have progressed by sharpening that skill, it is jarring to find that the barrier to their next job takes absolutely no account of it. You can spend years impacting or entirely setting the technical direction of a project or entire company through your writing (and verbal communication as well), and then find that all you're asked during your interview for your next job is to solve some made up problem using code on a whiteboard. It's bizarre.
      • sokoloff 7y ago
        Your comment made me realize that even when we hire execs/senior execs, I can't recall ever specifically evaluating their writing skills. I only recall doing so for dedicated comms people, but it's just as relevant for execs and yet we don't seem to do it there either.
  • daveslash 7y ago
    Writing well may not be undervalued from a managerial standpoint, but I think many individual engineers undervalue developing good writing skills. That assessment is based on personal & anecdotal experience. Writing skills are a subset of communication skills. Communication is largely "getting the idea(s) in my head into your head with as little ambiguity and confusion as possible". Once a team is is reasonably large and diverse, this becomes very valuable and important to the individual engineer.
  • sanderjd 7y ago
    It definitely is undervalued. There is very direct evidence of this: technical writing plays exactly zero role in the hiring process. That process tends to be more than 90% or so focused on coding, and the other 10% is not writing, it is some combination of credentials, knowledge of current trends in the field, ability to seem like you would fit in at the company, and drawing system diagrams. But technical writing - in code documentation, design documents, task definitions, bug reports, emails, and chats - is often the greater portion of my job in a week, and it is pretty much always the more important part. I agree a bit more that "empathy" is sometimes used in a BS-y way, but at its core it just means seeing things from more than only your own perspective. Which is definitely an important thing to do. I would probably agree that it is undervalued, though there seems to be more awareness or at least lip service to it than to the importance of writing.
  • munificent 7y ago
    This is such a weird take. Your own comment here is an example of writing for humans that uses emotional language to try to persuade an audience. By writing this comment at all, you imply that your comment is wrong.
• jsty 7y ago
  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 system design was flawed or it doesn't address any real user needs.
  • sokoloff 7y ago
    “Writing is nature's way of telling us how lousy our thinking is.” ― Leslie Lamport
    • tombert 7y ago
      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.
      • dmreedy 7y ago
        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.
    • tomfern 7y ago
      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.
      • ithkuil 7y ago
        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
    • 7y ago
• simonw 7y ago
  The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like. This article is absolutely spot on when it points out that these skills become increasingly important as the size of an engineering organization grows. The biggest challenges in engineering at scale (scale in terms of complexity and size of the team) are around communication. Good writing is how you scale your communication, especially if your team aren't physically co-located. I don't think software engineers talk about or think about how to improve technical writing nearly enough.
  • mdorazio 7y ago
    Absolutely. And if you ever want to strike out on your own and start your own company (especially if you want funding for it), writing well is critical and can't always be outsourced.
  • dsfyu404ed 7y ago
    A good tutorial is it own documentation and good documentation is its own tutorial. I've yet to find anything that packs a bigger punch than screenshots annotated with MS paint paired with concise description.
  • bongobongo 7y ago
    The problem is that many organizations prevent their IT/engineering departments from professionalizing in a way that would allow for this. "We need a month to iterate over requirements and specification" can land like a lead balloon in any project management meeting, because the _non_-engineers don't see any value in it.
    • aphextim 7y ago
      When you try to explain to them that implementing a new system they want isn't as simple as installing new kitchen cabinets. Try to explain that it is like when you install a kitchen cabinet and then open up the door and it leads to an entire new kitchen cabinet set which also needs to be worked on and that cabinet also has it's own kitchen cabinets that need redone as well. A lot of times (at least where I work) management has a hard time seeing all the layers in the IT systems they use and what appears to them as a simple surface fix/change isn't always the case.
• tombert 7y ago
  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 John Steinbeck or Mark Twain, but I've always felt that if I wanted to be treated like a grown-up, I should write like a grown-up, and as a result I have tried to write well. I try and be understanding of typos, because those are just honest mistakes, but when an adult sends an email to me saying something like "when r u going to do this?", I get a bit annoyed.
  • enriquto 7y ago
    I used to think like that (being the kid that wrote well in school). But now I'm not so sure anymore... Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.
    • tombert 7y ago
      Oh, most of my coworkers are smarter than me, so I'm certainly not trying to make an assessment on their IQ or any nonsense like that. That said, I do think that writing smsesque (which I am going to steal for the future because I had never heard that term before) is a really good way to make yourself look dumber, especially to non-engineers. Even if my long and rambling writings lack substance, they still typically give the optics of someone who is smart. Is that the way it should be? Probably not, but I don't make the rules.
      • enriquto 7y ago
        > I do think that writing smsesque (...) is a really good way to make yourself look dumber, especially to non-engineers. Maybe they do that in purpose, then?. They do not need to be admired by everybody, especially not by non-engineers. Like the very rich people who dress extremely humbly, with torn-down clothes.
• petra 7y ago
  What about using writing to sell an idea ? My friend, who isn't good at interpersonal skills, is trying that. Can this work for him ? or is the trust created via face-to-face is irreplaceable for convincing others ?
  • uberstuber 7y ago
    If anything, good writing is more persuasive than face-to-face. A well written document carries some gravitas. Of course, you have to get decision makers to read it...
• jambutters 7y ago
  https://youtu.be/vtIzMaLkCaM https://youtu.be/vtIzMaLkCaM has very interesting tips on writing. tl;dw : you have been taught to write to people(teachers) who are paid to care about your writing.
• deleted 7y ago
  [deleted]
• 0xdeadbeefbabe 7y ago
  Reading is undervalued, and just writing better won't fix it. Good readers tend to underestimate this problem obviously. If you read the article I bet your colleague didn't, and he or she isn't interested in reading your better-catchy-succinct-effective-if-not-superlative writing either, and he or she is going to rewrite the system. (Oh but exceptions I can think of are Harry Potter, and also the LKML as a vehicle for developing linux)
• mnorton 7y ago
  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/dp/020530902X/ref=sr_1_3?crid=2MK6DSC2Y7SVJ&keywords=elements+of+styles+strunk+and+white&qid=1559316830&s=books&sprefix=elements+of+style%2Cstripbooks%2C144&sr=1-3 https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...
  • criddell 7y ago
    If you've read Steven Pinker's book Sense of Style, I'd be interested to hear where it falls short in comparison to Elements of Style.
    • Veen 7y ago
      Elements of Style is the one that falls short. Pinker’s book is based on an understanding of how grammar actually works. Strunk and White is not.
  • afarrell 7y ago
    A good follow-on to this is the book Style: Towards Clarity and Grace.
  • lukeHeuer 7y ago
    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/id500673866?i=1000394239451 https://podcasts.apple.com/ca/podcast/against-strunk-white/i...
    • mnorton 7y ago
      There's definitely stuff in there that is dusty for sure. Thanks for this.
• beat 7y ago
  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 going to be a win for them is a sales problem. Clear writing is only a means to that end.
  • beat 7y ago
    And as a follow-on comment rather than an edit... There's nothing smarmy or dishonest about sales. Misleading sales is bad sales. The best salespeople are focused on fulfilling the customer's needs, not selling the product. The product sells itself once the customer understands that it fulfills their needs and offers them real benefits relative to the expense. And expense isn't just money. It's time. It's risk. It's learning curves. Customers often don't understand their own needs very well, so a big part of sales is helping the customer understand their own problems, in order to provide valuable solutions. The engineer who can really dig into requirements, really get to understand the customer and help the customer understand their own needs, and then offers a working solution, with clearly stated benefits and clearly stated costs, will do far better.
    • hyeomans 7y ago
      Do you have any good resources on sales?
      • beat 7y ago
        Start with How to Win Friends and Influence People, by Dale Carnegie. Ignore the cheesy-sounding title; this book was written in the 1930s and has been in print continuously ever since, which speaks to its effectiveness. I also recommend To Sell Is Human, by Daniel Pink (and all of Daniel Pink's other books, as well).
        • 7y ago
• inflatableDodo 7y ago
  Writing well? I've had to read engineering drawings for QC in a precision engineering shop working with critical industries. Screw grammar and style being undervalued. You get told to fuck off if you complain about spelling. edit - there is a pathological aversion to updating a drawing, not because of the work, but because of the process. People will do almost anything to avoid having to get an update signed off.
  • sixstringtheory 7y ago
    Assuming QC == quality control, I find that attitude highly ironic. Measure twice, cut once. Take the time to write carefully up front and proofread, before you submit it to a lengthy process.
    • inflatableDodo 7y ago
      I think a lot of people doing the drawings are either dyslexic, or maybe just do not care. Also, engineering companies don't tend to have proofreaders. I can proofread, but learned quickly that I should not bother proofreading the drawings that came through. All it ever achieved was a torrent of abuse, combined with a flat refusal to even think about getting a new drawing issued.
• mabbo 7y ago
  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 design? Write a 6-pager (often 10-15 pages with appendices) explaining what, why and how you're going to build the system. I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting. It's very weird for newcomers, but I don't know anyone who finds that it isn't better than the alternatives.
  • yomly 7y ago
    It's a bit fuzzy whether people from CS backgrounds acquire this skill organically, but the style guide / format of the x-pager docs felt very familiar to scientific publishing. The main value of it felt that enshrining factual objective information and basing all discussion around that.
    • deleted 7y ago
      [deleted]
  • scarejunba 7y ago
    Interesting. Is the advice published externally somewhere? The Everything Store does mention the silent reading bit.
    • adenverd 7y ago
      +1 would really love to read any style guides or writing class materials from Amazon, if anyone can share!
      • sandGorgon 7y ago
        +1 on this. Any info on what the writing class covers ?
• mrmrcoleman 7y ago
  Fully agree and I'd expand the point to cover communication in general. Explaining ideas clearly with text or voice is one of the characteristics that I've noticed in high-functioning engineering teams. I did a talk[1] a few years back about my experiences helping a team to improve their communication skills. What surprised me was the emotional complications that prevent people from communicating effectively. [1] https://vimeo.com/134601419 https://vimeo.com/134601419
  • sandGorgon 7y ago
    Is there are tutorials or training material you would recommend. I have been hearing "plain writing" more and more...but not sure if it is the right thing.
    • mrmrcoleman 7y ago
      I’m sorry I don’t have any link to hand that would help with writing.
• aresant 7y ago
  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: "the reason writing a good 4 page memo is harder than "writing" a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related"(1) 2) Message Accessibility - Making your message broadly accessible is a good forcing function to writing clearly. An easy "hack" in this department is to utilize the "gunning fog index"(2) which is a structured way to estimate "the years of formal education a person needs to understand the text on the first reading" and there are many tools online that can spit out a score. (1) https://slab.com/blog/jeff-bezos-writing-management-strategy/ https://slab.com/blog/jeff-bezos-writing-management-strategy... (2) https://en.wikipedia.org/wiki/Gunning_fog_index https://en.wikipedia.org/wiki/Gunning_fog_index
  • turingbike 7y ago
    Surprisingly, there are a lot of good tips in the US Gov's Plain Language Guidelines https://www.plainlanguage.gov/guidelines/ https://www.plainlanguage.gov/guidelines/
    • charliepark 7y ago
      That's an excellent resource. Thanks for sharing it.
  • fanf2 7y ago
    It is more accurate to credit Blaise Pascal for that aphorism https://quoteinvestigator.com/2012/04/28/shorter-letter/ https://quoteinvestigator.com/2012/04/28/shorter-letter/
• hbarka 7y ago
  In the US university system there are undergraduate requirements called distributional or general education requirements. The breadth of the courses cover humanities and arts, social sciences, and other classes under a Liberal Arts category. I wonder if there are similar requirements in other countries. Does an undergrad degree, say in India, have an apples-to-apples equivalent to an undergrad in the US with respect to the distributional requirement.
• nihil75 7y ago
  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").
  • idlewords 7y ago
    This could have been written better.
  • munificent 7y ago
    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.
• dano 7y ago
  I recommend the following book on a regular basis to those in newly minted leadership positions. https://www.amazon.com/Writing-Works-Communicate-Effectively-Business/dp/0060956437/ https://www.amazon.com/Writing-Works-Communicate-Effectively...
• michaelmior 7y ago
  I recently had a colleague recommend Writing for Computer Science[0]. It feels targeted more toward academics, but there's plenty of useful things in there. [0] https://www.springer.com/us/book/9781447166382 https://www.springer.com/us/book/9781447166382
• wazoox 7y ago
  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 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." So it was done this way, and the courageous people of the developers wrote unit test scripts, to validate the proper functioning of each new version, whereas until now they were content to test by hand and whatever popped into their heads. Then rivers of milk and honey flowed on the earth, and the customers gave them much money; then the Lord saw it and was pleased.
  • paulcole 7y ago
    Do it once and it's kind of clever. Do it twice and it gets a lot less fun.
    • wazoox 7y ago
      You have to find a different angle each time.
      • CalChris 7y ago
        Or pick your moment.
  • TomVDB 7y ago
    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 with: "First test new features before sending to customer." ... ... I think. What a way to waste time of your audience.
• JoeAltmaier 7y ago
  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 paragraph.
  • rgoulter 7y ago
    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.
    • abhishekjha 7y ago
      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?
    • microtherion 7y ago
      > 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. I agree, but maybe that style of writing has evolved for good reasons? In engineering, it seems to be a common personality trait that when presented with conclusions first, we tend to formulate reasons contradicting the conclusions, and then dig in on those reasons, to the detriment of trying to follow the explanations that follow. In the military, on the other hand (which has been cited as an example of "bottom line first" culture in this thread), people seem more inclined to follow orders. Anecdotally, in my limited time in the military, I had the opportunity of observing both kinds of personalities, and they did NOT mesh gracefully…
      • rgoulter 7y ago
        I really love this blogpost which discusses these two personalities, in the context of "corrections from strangers on Twitter". Some see corrections as "sharing information"; others see making corrections as asserting status/dominance which disrupts social harmony. https://status451.com/2016/01/06/splain-it-to-me/ https://status451.com/2016/01/06/splain-it-to-me/
• franciscop 7y ago
  I don't feel like it's undervalued; 93% of developers get frustrated by it: - https://opensourcesurvey.org/2017/ https://opensourcesurvey.org/2017/ It is a fairly thankless job because it's more difficult and the concept of bugs or missing features is fairly fuzzy (compared to software). But it is highly valuable, and people do notice it. I attribute most of my open source popularity/stars at decent/good docs+examples in my libraries, like the most recent one: https://github.com/franciscop/ola/ https://github.com/franciscop/ola/
• tmaly 7y ago
  I would highly recommend the book The Pyramid Principle for improving your writing in a professional environment.
• everyone 7y ago
  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.
  • necovek 7y ago
    You overestimate people's ability and enjoyment in reading concise writing that has each word measured carefully. In order to pass an exam in university, I had to deliberately repeat myself in a few subtle ways, only to be commended how I managed to get my points across very concisely. I find that writing well is somewhere in the middle: people are used to skip-reading, so being very concise is counter-productive: unless you want to repeatedly point them to actual bits of text that answer their question but which they probably went over as only fill-text. So, I prefer to state my position concisely at the front, benefitting people like me who prefer it that way, and then expand it with examples and more elaborate arguments for those that need more. Like this post: the whole point is in the first sentence. The rest is just for the majority who'd basically not even read it, let alone bother to understand it. (As a consequence, I often miss the happy middle and become too elaborate: it's a struggle :))
• joshuacc 7y ago
  Along these lines, I have a half-completed book on GitHub titled Prose for Programmers: https://github.com/joshuacc/prose-for-programmers https://github.com/joshuacc/prose-for-programmers I started it because I found that being able to write effectively was my biggest advantage at work. Compared to others who were at least as technically competent as myself, I was more often able to persuade others to take the course of action I prefer.
• deleted 7y ago
  [deleted]
• mlthoughts2018 7y ago
  I actually have found that if you are an engineer who displays well-rounded skills in multiple disciplines, like business acumen, communication, writing and conflict management, this causes managers and non-engineers around you to view you as a threat, and they will work harder to undermine you and try to box you into a “engineer only” label. Above all, you won’t be rewarded for these other skills, despite how vital they are.
  • beat 7y ago
    Ugh. In that case, you should move to someplace that values those skills.
    • mlthoughts2018 7y ago
      It has been this way at every job (7 companies now, ranging from huge & bureaucratic to medium & popular to super new start-up). Whether it has been at a major tech company or the latest & greatest start-up, people have universally acted this way everywhere, often while talking at length about how their company culture causes them to not act this way.
• vidro3 7y ago
  second only to reading comprehension
• piaromba 7y ago
  I recall my technical writing class in collage was actually pretty good and it was a required course. But when i went into industry there was not monetary connection to writing quality. Sometimes it is even better for developers to have convoluted documentation because then they make themselves indispensable to maintenance in the future.
  • pickle-wizard 7y ago
    I too took a technical writing class in college and it was very helpful. I used to be a pretty good technical writer early in my career. Everything I did was documented throughly. Anyone could read my documentation and pick up the project. Then we had a management change. I would literally get yelled at by my director because I was wasting time creating documentation. So I stopped. Didn't document shit, and the yelling stopped. I'm at a new job now, and I'm trying to get back in the habit of documenting everything. Though those skills are very rusty.
• bongobongo 7y ago
  I don't think this and other so-called "soft" skills are undervalued by engineers themselves. A good writer/communicator brings immediate value to any engineering team and will be treated as such, usually. It's the pointy heads and the business side of the operation who don't value it, because it's not sexy. IT and software engineering are abstract to them, so when they don't see "hands on keyboards" (writing code), they think no work is being done. Software engineering will remain in its infancy as a "profession" until software engineers themselves organize and better assert their own professional standards. Writing and iterating over documentation is an ISO standard that is ignored 99% of the time. If you ignore your professional standards, you are not a professional, no matter your title or your salary or even your field of work.
• growlist 7y ago
  Agreed, hugely undervalued and I would argue pretty rare. My formal grammar is pretty poor and I mainly operate on what sounds right, but nonetheless I am commonly shocked by the basic mistakes that are made by most people including very senior people - poor punctuation, ambiguities, misuse of apostrophes etc. I don't know if this says something about education in the UK? But the main message to me is - things other than writing matter when it comes to getting ahead. Why bother showing it off or improving when it will likely just get you labelled as (if you can believe this still happens in a business like tech - but it does) a geek.
• jlmorton 7y ago
  > I have noticed a few skills that people often underestimate the importance of developing. Skills that add a significant boost to the impact of any developer. One of these ones is writing. Heh.
• soneca 7y ago
  This article pitches the idea that writing is an important skill to advance your career. It makes the point that you will be better at spreading an idea and influencing people. I agree with this, but to me personally, the more compelling reason to improve your writing is that will improve your work (not necessarily your career). It is more about better communication than influencing people. I want people to more easily and reliably understand what I am trying to communicate. Understand my ideas, my doubts, my suggestions, my attitude, my feelings. My writing was definitely valuable in my transition to software development two years ago.
• JustSomeNobody 7y ago
  I get that times are changing, but I still believe that if you choose not to write well, you just aren't being professional.
• kashyapc 7y ago
  Especially for those who work remotely, I (English is my third language) can't overstate the importance of deliberately working on writing skills. As remotees, we are often judged by our words, whether we like it or not. A couple of recommendations: • Many here might've already come across it, but is always worth bringing up: William Zinsser's, On Writing Well. In which, he urges us to write with "clarity, simplicity, brevity and humanity"; tells us "the intangibles that produce good writing—confidence, enjoyment, intention, integrity"; reminds us to "remember that what you write is often the only change you'll get to present yourself to someone whose business or money or good will you need"; and much more. • The equally excellent book, Clear and Simple as the Truth[2]. In this rigorous work, Thomas and Turner describe a style of writing that rests "on the assumptions that it is possible to think disinterestedly, to know the results of disinterested thought, and to present them without fundamental distortion. In this view, thought precedes writing". And the book also has a chapter that is aptly titled, The Museum, a "guided tour through examples of writing, both exquisite and execrable". The second book, I suggest to slow-read it over a period of several months to digest it (and perhaps even do the exercises in the chapter titled The Studio, if you're a non-native speaker), not least because, as a certain Roman Stoic urged us, to read attentively—not to be satisfied with "just getting the gist of it". [1] https://www.goodreads.com/author/show/7881675.William_Zinsser https://www.goodreads.com/author/show/7881675.William_Zinsse... [2] https://press.princeton.edu/titles/9445.html https://press.princeton.edu/titles/9445.html
  • Bekwnn 7y ago
    I'd also recommend "It Was the Best of Sentences, It Was the Worst of Sentences" for some easily digestible writing on how to write easily digestible writing. It's probably one of the most useful type of writing skill to have as an engineer.
• spurcell93 7y ago
  This is one thing I love about stripe. There are a ton of resources to write, and every employee is encouraged to communicate at a very high level.
• dkarl 7y ago
  I think people appreciate this about other people, so if there's a place where it is undervalued, it's when people evaluate themselves and their opportunities for improvement. I remember Bjarne Stroustrup saying that an important sign that a person could become a good programmer was that they could write clearly in their native (natural) language. I can't find that quote, but I did find a 2013 interview [1] in which, forced to pick three key pieces of advice for budding programmers in their early twenties, his #2 was, "Learn to communicate well, verbally and in writing." [1] https://yourstory.com/2013/12/bjarne-stroustrup-interview https://yourstory.com/2013/12/bjarne-stroustrup-interview
• amirhirsch 7y ago
  Did anyone else find this article to consist of ironically poor writing? The blog post contains of a lot of fragments, run-on-sentences, unnecessary pauses, mixed tenses, dangling clauses, use of the passive voices, and no Oxford comma!
  • d23 7y ago
    I'm surprised this is so far down. I'm assuming most people commenting didn't actually read it and are just agreeing with the sentiment. Perhaps the author is not a native language speaker? That being said, I'm not sure why you'd write an article about the importance of writing if your writing is... below average at best.
    • amirhirsch 7y ago
      I was late to the party so the general conversation seems to have taken a different direction, but glad I'm not alone.
  • NateEag 7y ago
    Yes, the article was mediocre writing at best. The author made his point clear, so he achieved the core goal of technical writing, but the writing itself was clumsy and distracted from his message.
• apo 7y ago
  I noticed the article appears to contain a single point of evidence supporting its main claim: > Don't take this advice just from me. Take it from others, like employee #8 and now SVP of engineering at Google, Urs Hölzle who also says that writing clearly is an important superpower for engineers. The link goes to a LinkedIn page with a brief quote captured in raster image format. This is weak evidence for a topic that will certainly be met with strong resistance from the target audience. The author could make a much stronger case by interviewing a few people at top companies specifically on the topic of engineer writing. These people should be in a position of making promotion decisions. The author might coax out of them illustrative anecdotes that show exactly how poor writing skills can keep an aspiring engineer down. How much money in lost wages is my crappy writing costing me? What are my job prospects if my writing doesn't improve? What exactly will better writing allow me to do that I can't already do? These are all questions that demand answers (and evidence) from people with 10 other things they might be doing. Another idea: what studies (if any) have been done on the correlation between writing quality and promotion within technical organizations? For that matter, how does one objectively measure writing quality? After all, you're much more likely to improve something you can measure. A hallmark of good writing (of any kind) is ample evidence to support claims. Engineers and scientists are a skeptical bunch, and so this point applies even more to technical writing.
• xrd 7y ago
  Popular opinion almost makes it seem like "writing well" (for human consumption) is almost the opposite of "writing good code" (for computers). To be regarded as a great programmer, you need to know all the arcane details of a system, where those are the intricacies of a particular language or framework, or the small details of how a computer system works. It's the minutiae that counts. With writing for humans, you need to have a very high level overview of things. You need to speak broadly and appeal to a common human understanding. The top level understanding is what matters. Coding interviews reflect the change the industry is sensing and what this author puts well: the worst coding interviews are where they ask you about some small detail of a language or algorithm. It's a gotcha test. The better interviews ask you to show how you holistically approach a problem.
  • mont 7y ago
    Also I'm not sure how useful it is to test people on remembering minutiae of a system on the fly. How often are you correct about small details of a system you work with on a daily basis on the first try?
  • ragona 7y ago
    I disagree -- there are many situations in which your writing must display both a very detailed understanding of a system, AND a very detailed understanding of your audience.
    • thfuran 7y ago
      And, similarly, you can code perfectly functional code that properly handles all the minutiae but is totally inconsistent with the general structure or style of the project and that is bad. The high-level considerations are still important there.
      • ragona 7y ago
        Agreed! The intersection of coding and communicating is really interesting. That is my personal bar for a really phenomenal programmer — someone who can produce code that communicates ideally to both humans and computers. And this gets harder and harder depending on the task! It’s really tricky stuff.
• starpilot 7y ago
  how too rite good?i dum dum
• siculars 7y ago
  I say it all the time: a significant fraction of my job is to read and write google documents. I’m either writing docs or I’m reading/commenting on docs someone else wrote. Reading and writing are foundational skills needed in virtually every field. Especially especially especially at google. /I work at google/
• ragona 7y ago
  This falls into the category of a much wider undervalued engineering skill -- communicating well. The best engineers tend to be excellent communicators. There is a whole group of extremely talented programmers who just don't understand why they aren't getting ahead, and nine times out of ten the answer is that they suck at communicating.
• mailslot 7y ago
  This is literally how I get “impossible” changes to happen virtually anywhere. There’s so much psychology that goes into the impact of the written word. Don’t spread my secret. :(
• deleted 7y ago
  [deleted]
• mattjaynes 7y ago
  Basically, here is what I tell myself when I'm going to write something for an audience: • Nobody gives a fuck ABOUT ME or how cool or awesome I am. • People only care about how awesome THEY ARE. • I am competing for their very short attention-span. Facebook, Netflix, and porn are my competition. This better be pretty compelling if they are not going to immediately hit their back button. • I either need to address some real PAIN they have, or be pretty amazing at entertaining them. In most cases, addressing a real pain is easier. It's much harder to entertain better than porn, breaking news stories, etc. • Structure for pain is clear: 1. Identify the pain and show how much it hurts and costs them 2. Show them the solution, and how good it will feel to stop losing and start winning 3. Anticipate and address their concerns. Are they worried about cost? Are they worried about how much work it will require? Are they worried what their boss or customers will think? Etc. Think of the most likely concerns or objections they will have and explain how to resolve them. All or most of their questions should be answered so that there is nothing in the way for the next step... 4. Call them to action to do something. Use your tool. Change a behavior. Etc. The structure can vary a bit, but this is generally the structure. In a purely technical article, you may have very short sections on the pain, then spend most of the time on the solution. If the purpose is more for sales, then you'll want to have it more balanced and focus a lot on resolving concerns. The article should be clear enough and structured enough so that every paragraph can have a headline. And a reader should be able to scan the headlines and know very quickly and clearly without having to think "what is this article about?" If the article feels or looks like work to read, they will give up right away and you've lost them. There has to be something really compelling for them. How will this make them more awesome? They don't give a fuck about anything else. They are milliseconds away from hitting their back button or searching for "nude guitar solos", so put the effort in to deliver something compelling and valuable. One well-thought-out clear useful article is far greater than a hundred jumble-thought aimless ones. Edit: formatting
• peter_retief 7y ago
  Good software skills are good writing skills
• fooblitzky 7y ago
  Another undervalued skill is speaking well. Since joining Toastmasters my career has undergone a step change. Managers perceive me as being much more effective, even though my writing and coding skills have only continued growing incrementally. It's the best investment of time I've ever made.
• dsign 7y ago
  Why is this skill considered "undervalued"? Could it be attributed to the gluttony of the industry for engineers? I have been in a couple of interviews to job applicants who couldn't bother less to fix typos and grammar in the first sentence of their CVs. The mere fact that we bothered to interview those candidates is disturbing.
  • kernx16 7y ago
    Was this rhetorical or are you actually confused as to why this skill is considered undervalued?
  • sam0x17 7y ago
    There are literally people who say "I hate verbal/writing stuff, I'll become an engineer instead" during their undergraduate education, little knowing that at least in industry these skills are critical.
• syndacks 7y ago
  I'm surprised this article doesn't suggest reading books. The best way to improve your writing is to read good writing.
• sam0x17 7y ago
  Right up there with "communicating well", and the often important "managing the expectations of non-technical stakeholders"
• Maro 7y ago
  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 or not-X), and they're super successful, in so far as their companies are successful / they are in high positions. 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.
  • alexpotato 7y ago
    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 pilot got to fly with an ace and occasionally get kills they wouldn't have gotten otherwise.
    • Maro 7y ago
      Afaik in "modern times" at "modern companies", ie. startups, everybody does their own emailing. I worked at Facebook, maybe Zuck/Sheryl has somebody helping them with email (I don't know), but they're obvious outliers.
      • alexpotato 7y ago
        I meant more in the sense of "They have other people write and then send the important email/docs etc" and not the "hey, can you help me write this email". I've helped several managers over the years write emails and I'm pretty sure they didn't then go tell everyone "Yep, I had help with this email" so I think it be surprising to some folks how often this happens.
• lpolovets 7y ago
  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/1127348174404890625 - https://twitter.com/david_perell/status/1124002449646395392 https://twitter.com/david_perell/status/1124002449646395392 - https://twitter.com/david_perell/status/1116485842615377921 https://twitter.com/david_perell/status/1116485842615377921
  • chrshawkes 7y ago
    I would say communication overall which includes reading, writing and vocal communication.
  • stingraycharles 7y ago
    I can also recommend June Casagrande, who has lots of great recommendations on how to improve your writing skills. This is one of her books I would recommend: https://www.amazon.com/Was-Best-Sentences-Worst-Crafting/dp/158008740X https://www.amazon.com/Was-Best-Sentences-Worst-Crafting/dp/...
  • ordinaryradical 7y ago
    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.
    • cosmodisk 7y ago
      One doesn't always get to meet people, sometimes and tbh quite often it has to be on LinkedIn,via email or even a letter.. Ability to do it well sets you apart and also brings confidence to those you try to communicate with.A well written proposal to a VC is 100 times better than some mish mash of words.
• jcaprani 7y ago
  Is anyone else seeing the irony of the poor writing in this article?
  • _hardwaregeek 7y ago
    In fairness, the author is not a native English speaker. And he makes his point with clarity and cohesion. There are some awkward phrases, but by engineering standards his writing is perfectly fine :D
  • amirhirsch 7y ago
    I enjoy the coincidence of our comments asking this same thing as a question.
• kazinator 7y ago
  > It is with a larger organisation that writing becomes important for messages to reach a wider group of people. I'm not able to fully agree. An engineer is more likely to write text that reaches a customer in its original form in a tiny startup or consulting firm than in a big organization. The larger the company, the more of a cog you are with specialized tasks. Writing? That's a documentation person; just give them a rough draft capturing all the info. Customers typically talk to customer support, not to you. Customer support people have to write well, to be sure. If the engineer started in a small organization which grew, but that engineer's responsibilities grew in proportion also, then that is apples and oranges. You have to compare how much writing is required in comparable roles.
• dboreham 7y ago
  See also: critical thinking
  • pistachios 7y ago
    What is a good book on this subject?
• deleted 7y ago
  [deleted]
• lgleason 7y ago
  As an engineer and now an author of a technical book I definitely agree with this. I have seen many places where they have a talented engineering team that cannot communicate what they have created etc. to everybody else. The worse anti-pattern is when they hire technical writers with no knowledge of the domain (or dev skills) to create documentation on how to use API's targeted at developers... The end documentation from that effort, unsurprisingly, is often borderline incomprehensible.
• cosmodisk 7y ago
  I think writing doesn't get anywhere near the attention ot should be getting.I've met and I work with some really great people but boy oh boy they struggle to write.I'm not talking about producing the next bestseller but simply communicating simple ideas. I read what some of them write I think: wtf...if you were only able to write better you could be reaching the sky.. Technical capabilities+ ability to communicate well in writing is a killer skill and can literally elevate people to a whole new level..
• ironman1478 7y ago
  At USC, they had multiple mandatory writing classes and I felt that the people who did well in those classes did well in engineering too. I think there is a high correlation between being able to clearly write something down and explain it and understanding the concepts.
• ericmcer 7y ago
  There are kinda two disciplines here, writing something that tries to convey a complex concept is important, but it's also important to be able to tersely describe a problem, and use correct, agreed upon language to do it. Compare: Wrong error message shows on Xm-z pages username input. Xm-z page, username input, Error message incorrect. I would argue that having agreed upon naming, and explicit syntax for how to describe issues/improvements in-between your team members is almost more important than being a good writer. The bottom sentence isn't even grammatically correct.
• heisenbit 7y ago
  In the Middle Age we needed to thumb through huge binders located in a room close to the mainframe. Tedious. Then we could buy the books. We still needed to thumb through and it took time. The the wastage of engineering hours was decreased by putting the writing to low level engineers. That was a good idea as it saved money. That idea could be made even better by having documentation moved to another location by even lower paid staff. Great financial results! In the meanwhile we got patterns and realized that all software is created the same. Documentation can be recycled and continuous releasing saves time for unneeded reviews. Software and its documentation is really just assembling blocks. Learning from the leader in that space, Ikea's manuals yielded even greater results. And with additional ingenuity video was introduced. Saves trees, Ikea could learn from us. These days one does not need to read much anymore, just google a video. And if a problem can't be solved, then agility comes to rescue. Lean development means problems are solved when needed and that is what agile users are for.
  • m_fayer 7y ago
    I'm not totally sure what you're doing here, but I like it.
• deleted 7y ago
  [deleted]
• bearcobra 7y ago
  One thing I love to do is send any major communication I've written through text to speech. I've caught soo many mistakes that Grammarly or Word didn't when I hear it.
• zadkey 7y ago
  Also, documentation skills.
• abbadadda 7y ago
  "One of these ones is writing." - I couldn't help but laugh at this. Would have been a little more concise to drop the "ones."
• jestinjoy1 7y ago
  I am from India and here writing skill for engineers is not valued at all. As someone into research, I found it important when I started sending papers. Academia here is not giving importance to the writing of its students.
• ulisesrmzroche 7y ago
  Engineers should write more science fiction, especially software engineers. I’ve already died on this hill tho.
• pugworthy 7y ago
  The ability to be "agile" with writing is pretty important to some. I sometimes find I'll edit and revise (and tweak) a gamedev stack post many, many times over just little things.
• jacquesm 7y ago
  Funny, I never thought that that would be the hill one of my plans would die on. Writing well - and reasonably quick - is rare, when you take the intersection of people that have that skill with people that are technically inclined the resulting set is super small.
• tw1010 7y ago
  Ugh, I don't understand why people keep recommend the Pinker book about writing well. Pinker has the most formal god awful style I could imagine. There are so many better writers to learn from. Don't fall for mimetics guys.
  • criddell 7y ago
    Can you be more specific? I started reading it and I'm actually enjoying reading about writing.
• now 7y ago
  ”Writing Good”, there, I fixed it for you.
• Envec83 7y ago
  I completely agree. In fact I created https://www.dailywritingtips.com/ https://www.dailywritingtips.com/ (more than 10 years ago) for this exact reason.
• eutropia 7y ago
  I sometimes think that programmers come in two types: mathematically inclined or linguistically inclined. Think sorting vs parsing. I only realized this after testing out of and skipping all English and writing requirements easily, but having to retake several mathematics courses during my time in engineering school.
• antpls 7y ago
  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 objective.
  • duckmysick 7y ago
    > 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.
• Myrmornis 7y ago
  I agree that writing well is extremely important. However people like to do so much verbally in meetings, that what you write will probably not be read carefully.
• zn44 7y ago
  This article comes at a perfect time. As I want to work on my writing skills. I’ve found many recommendations in this thread on how to improve your skills but nothing focusing on technical writing. Any recommendations for materials specifically for developers?
• kinkajou 7y ago
  I've been interested improving my technical writing for some time but don't really have any idea what good tech writing looks like. Can someone suggest some examples of what you consider really good documents?
• keitsist 7y ago
  I know this is an off topic question but would anyone know of a similar site/author with a electrical and/or mechanical engineering focus/background?
• deleted 7y ago
  [deleted]
• hwj 7y ago
  For German speakers: there's a good book about writing in computer science called "Technisches Schreiben (nicht nur) für Informatiker"[1]. The appendeix contains a funny correspondence between an author and his publisher whether "FORTRAN" or "Fontran" is correct. [1]: https://www.hanser-fachbuch.de/buch/Technisches+Schreiben/9783446409576 https://www.hanser-fachbuch.de/buch/Technisches+Schreiben/97...