18 ms·

How to communicate effectively as a developer

549 points by karls 4y ago

zerop 4y ago
Very good old thread on HN on similar lines (Ask HN: How to speak like a leader, not like an engineer?) https://news.ycombinator.com/item?id=19349676 https://news.ycombinator.com/item?id=19349676
ramilefu 4y ago
The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. I think this is the origin for much of the friction we experience in collaboration and documentation. It’s easy to build something, ship it, and move on. That’s the dream we are sold as well: changing the world, one line of code at a time, from our basements. I would love to see more focus on writing in our industry. Unfortunately, I haven’t experienced much improvement here in the last decade of working in the industry, across several organizations. The writers among us are quite the minority.
- scruple 4y ago
  > Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. They have to write the code because that's what is demanded of them. If management would prioritize communication they would get more of it.
- batesy 4y ago
  Seems like a pretty significant opportunity to level up for those willing?
  - ramilefu 4y ago
    Certainly. I’ve leaned into it, when given the chance. As the author writes, it definitely makes you stand out, if you are willing.
  - soneca 4y ago
    It definitely helped me a lot in my career. It is hard to single out its impact, as good writing also help me demonstrate other non-technical qualities like diligence, trust, problem-solving. But I might take a guess and say that about 30% of my salary is due to good written communication skills
  - KptMarchewa 4y ago
    On the contrary, a lot of businesses punish it.
- ngrost24 4y ago
  Personal opinion or anecdata: Is it possible that communication is "detested" because it's not valued within the developer group? Many times, when someone speaks of a 10x software engineer, the gut feeling is of someone that provides the output (measurable in code) of 10 developers, not that he's able to have an impact in the organization through communication as 10 developers (breaking silo-s, syncing teams, etc), although this might be closer to the truth and what the duties of some staff and principal level developers includes. In addition, rarely communication is valued within the companies where we work. Most aspects of documentation, whether vocal or written, are hard to measure and as such are ignored when an evaluation of the "worth" of an IC is done. Personally, I think communication is relevant, but I also think that it's hard for developers to resist the sculpting that companies deliver to the employees on what is relevant in this field.
  - xbfjvusb6 4y ago
    This. I can tell HR, my lead and skip about how good my communication, soft skills and team work have been this year but come comp review they don't give a crapola about any of that. All they look at is how many sloc I've shipped.
    - scarface74 4y ago
      For context: I never really cared about yearly reviews or raises at my job before my current job. I knew they were going to be mostly shit anyway and that I was better off job hopping every couple of years to get a “raise”. Which I did six times between 2008 and 2020 after staying at my second job 9 years and getting 3% raises and seeing the bonus drop. That being said, the only formal raise/promotion process i know about are at tech companies. Promotions are based on “scope” and “impact” and not how well you code. The only time “coding well” comes into play is going from junior or mid. Even the interviews that determine your leveling is based on behavioral interviews and system design. I couldn’t interview for my next job and all I could put on my resume is “I wrote a lot of code”
    - karmelapple 4y ago
      I'm fascinated: does your company/manager truly track SLOC and promote based on that? Or is SLOC here more of a proxy for "features shipped"? Because if this is what's happening, I'd encourage two changes: 1. Communicate differently to HR, lead, and skip - either use different approaches of documentation, or point out different aspects of your contributions 2. If trying various different approaches don't work... leave. For communicating differently - I used to work at a large company, and our yearly reviews had places to capture accomplishments. That was a broad topic: it wasn't just features built, bugs fixed or identified, etc. It would also be totally appropriate to put ways you saved money or time on various initiatives, and I would frequently put down items like this. How do you communicate "how good" your "communication, soft skills, and team work have been this year"?
- PragmaticPulp 4y ago
  > The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. I wouldn’t say most developers fit this description, but there are a lot of people out there who embody this isolationist working style. Some times they can be fit into a team’s structure if you have a constant stream of small tasks that really can fit into a queue of fully-contained tickets and the person is capable of self-managing and delivering good work at a reasonable rate. However, that’s a lot of conditions that many people just don’t meet. Often what ends up happening is that the rest of the team and the manager have to put in extra effort to work around the person’s personality, which slowly drags everyone else down. That’s why it’s so important to screen for proper match during the interview process. I’ve seen a decent number of candidates who performed great on interviews, but couldn’t even pretend to be friendly during any stage of the interview. Surprisingly, a lot of them even seem to take pride in their demeanor. I think there’s a romantic idea out there of coding mercenaries who show up, take paychecks in exchange for writing code in isolation until they feel like moving on. This mentality sounds great to people who dislike communicating or working with others, but it’s incompatible with any teamwork or any project that must scale beyond a single person. Most of the work I’ve been involved with has required teams and teamwork, so these people don’t really have a place in the team.
- Multicomp 4y ago
  > The writers among us are quite the minority. Tell me about it. I'm lucky enough to have a supportive manager when I try to define my teams fitness functions, but getting the rest of the team to engage is an exercise in patience testing on all sides. They don't see the value in writing useless essays, shouldn't self documenting code be enough? I don't see the value in skipping high resolution communication up front so we can all waste time reworking the same problem for the 5th time that month because we forgot what we decided the 4th time we worked on it.
  - Nextgrid 4y ago
    One suggestion I would add is to make it easy to do the things you ask for. You're already having trouble getting your team to do it, the last thing you want is for them to have to suffer through shitty tooling to do so (and give them another excuse to skip doing it). Having documentation in anything Atlassian-branded (or similar garbage) is a no-no for example. That's one of the few cases where I would completely understand & support a developer outright refusing to do it. Writing essays might not be everyone's cup of tea (personally I'm fine with it as long as it will be useful and will not just rot away in darkness forever), but it's manageable with good tools. But if I have to wade through molasses like Confluence, I'd totally understand why nobody wants to engage and wouldn't even be mad at them. I'm generally not the kind of developer who hides in a cave, but as time goes on I understand them more and more - it turns out a lot of what these "cave" developers don't like involves absolutely terrible tooling that actually regressed over time (despite processing power and system resources constantly increasing).
  - P5fRxh5kUvp2th 4y ago
    document decisions and move on, why are you asking your team to write essays? Companies bitch about the performance of developers then ask them to do things like this. What's worse is when companies give developers all the responsibility and none of the control.
    - skydhash 4y ago
      Very much this. I like to write my documentation in Markdown because it allows me to be fast, while still having some structures. Then I paste the draft in Google Docs when I want to share and have people comment on it. Tooling matters and if I'm the one doing something, I want to actually choose how I'm doing it.
- Jensson 4y ago
  Developers hates communication since developers gets blamed for all communication problems even when they aren't at fault, until that changes most developers will hate it and refuse to do it since they got burned.
- throwawaysleep 4y ago
  > Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. And are also career incoherent and not valued. I get measured on points per sprint. Documentation, customers, and PR review does not help me hit key metrics, which is why I do all I can to get out of it, including being bad at it so that I am not asked to do it anymore. Nobody has ever scolded me or had a performance meeting with me about botching reviews, docs, or knowledge sharing. I am never asked about these in interviews either. The questions are all technical or generic "how do you handle disagreement with a colleague?"
- FoomFries 4y ago
  I would love to hear some resources for improving. Separating the chaff from the wheat on resources is always difficult for the layman, similar to learning an instrument for the first time. Most things I find on improving writing is related to fiction, and other areas of improvement seem unnecessarily anecdotal or story driven.
- hbrn 4y ago
  Spot on. But it's not even about writing. Developers hate communication, in any form. Going remote made it much worse, there's even more ways to avoid communication or turning it async. The only remedy I found is actively forcing people to talk to each other, starting with yourself. Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you. Need a code review? Grab the reviewer and walk them through the parts that are hard to understand. Designing a big piece of architecture? Instead of writing a thorough design doc that nobody will read, build a rough diagram and share it with the team immediately, preferably on a call. Writing documentation? Ask your team members what they want to see in it. Yeah, it sucks to do all of that when you're an introvert. But it gets easier with time. And hopefully you can find joy in the fact that you are delivering value X times faster.
  - skydhash 4y ago
    > The only remedy I found is actively forcing people to talk to each other, starting with yourself. That's not communication. That is forced socialization. There are things that are expressed more efficiently in spoken form, but the truth is that spoken words are ephemeral and the mechanism for storing and retrieving them are cumbersome. I like written communication, it forces you to be more structured in your thinking. And most importantly. It does not require another person to be actually present for this to happen. > Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you. I strongly believe that a review that can be done in a slack hurdle in 15 minutes can be done async in less. And there is the need to actually schedule for that hurdle. And in practice, every one of these hurdles will actually be surrounded by a period of non-productive time. Programming is thinking work. The actual coding, while visible, is the easiest part. We hate wasteful meetings because it contributes nothing to make thinking easier.
    - chrisweekly 4y ago
      Agreed; even further, the presence of even a small number of interrupts can disrupt the extended focus and context-building that are required to solve gnarly problems. See also pg's famous "Maker's schedule" post: http://www.paulgraham.com/makersschedule.html http://www.paulgraham.com/makersschedule.html
- devonkim 4y ago
  The issues I have are that developers tend to be bad at communicating even with each other. Communication as a discipline is a lot about meeting people where they are and this is difficult for basically everyone. The antagonistic attitude that developers seem to develop happen across almost every technical discipline whether it’s engineering or even trades. It may be even worse in trades given so much contact with the general public. If developers had to do customer support for their products as a rule you bet they’d get grumpy. However, I’d also say that interacting with the public probably makes most people in US retail grumpy, too. What I think I’m trying to say is that developers self-selecting out of things thinking they’re either not good at them or because they don’t like to do them is a bit of a luxury compared to most professions and many on the outside would look at that and feel there’s an attitude of arrogance and entitlement as such.
  - frenchman99 4y ago
    > If developers had to do customer support for their products as a rule you bet they’d get grumpy. Do you have data to support this? I would love to do customer support from time to time to better understand the users of the product I work on as a developer. But that request has been denied to me many times, in multiple jobs. To get people to communicate better, inspire them to do so and have faith in them.
    - devonkim 4y ago
      The data I’m seeing is from studies showing that developers doing peripheral duties and getting interrupted is one of the biggest barriers to productivity and quality among developers rather than training, education, or even raw IQ. Specialization of roles along with the political realities of corporations means that fiefdoms and exclusions will happen to though.
      - frenchman99 4y ago
        It is perfectly possible to do customer support on a specific schedule so that it doesn't become an interruption though.
- markrages 4y ago
  Sometimes I get the feeling that many developers are functionally illiterate. (In the https://quoteinvestigator.com/2012/12/11/cannot-read/ https://quoteinvestigator.com/2012/12/11/cannot-read/ sense.) I can spend as much time as I like writing comments or design documentation or whitepapers or commit messages, but nobody reads it. Maybe they will set up a meeting for me to read it to them.
  - justin_oaks 4y ago
    That's probably about right. But it's not isolated to developers. Most people skim or skip most instructions, documentation, warnings, etc. When I write documentation I hope that people will never talk to me because the information they need is already written down. But more often it's so I can redirect them to the documentation and implicitly require that they read it before they continue to talk to me. In other words, documentation doesn't usually prevent an interruption as much as it minimizes the interruption.
smileysteve 4y ago
The post begins with a preface about promotions for leadership from the Csuite. But I argue most Csuite and leaders are horrible at this too; I can't tell you how many all hands or emails I've been at where leaders use the abbreviations ELT, LT, ET, Csuite to refer to themselves -- and then use abbreviations for their move-the-needle projects and expect everyone in the room to know what they mean. Clear communication is great, especially in the remote world or when dealing with complex situations. But this isn't a trait that leaders have more than developers, and it's not a trait that particularly gets you outside the development track. Frankly, Ruby on Rails - and Rspec provide an example that developers should be very verbose -- in their method names, their file names, the description, background, context, and specific examples..
- samwestdev 4y ago
  > Frankly, Ruby on Rails - and Rspec provide an example that developers should be very verbose -- in their method names, their file names, the description, background, context, and specific examples.. Very interesting. Any practical example from said codebases?
  - smileysteve 4y ago
    https://edgeguides.rubyonrails.org/active_record_basics.html#naming-conventions https://edgeguides.rubyonrails.org/active_record_basics.html... https://www.rubydoc.info/gems/rubocop-rspec/1.25.1/RuboCop/Cop/RSpec/ContextWording https://www.rubydoc.info/gems/rubocop-rspec/1.25.1/RuboCop/C...
bsenftner 4y ago
This is one of the more critical issues of our industry, of our entire society actually.
magicalhippo 4y ago
Glancing over the examples, I don't see anything that's particularly unique to us developers. Support, marketing, sales, the bosses, our customers, they could all improve their communication in the ways presented here. For me, learning how to construct simple proofs during my early math classes at uni really helped my writing. It made me pay a lot more attention to what I'm writing, like ensuring arguments are laid out in a more logical manner and that references are clear. Not saying I'm exceptionally good at it. But given that language was by far my weakest topic at school until then, I've since helped both my SO and my sister gain over a full grade point increase in college on hand-ins and similar, just by looking over what they've written and doing some minor tweaks like reordering sentences to ensure logical consistency in their arguments.
luckylion 4y ago
Judging the right amount of information is what I struggle with. It's easier to judge whether someone wants more details when you're talking to them. It's harder when you're responding to a comment or in a chat. When it's too little, you go back and forth. When it's too much nobody reads your novel. I tend to go into too much detail, so I'm learning go where I feel is adequate and then take a few steps back.
- willjp 4y ago
  I think it helps if you can preface your paragraph with a short summary. The reader then knows generally the scope of what you are trying to communicate, and the details become more approachable. That said, I’m pretty horrible at this balance as well, and often lean towards long form “walls of text” that eat office hours, then work OT to compensate.
  - luckylion 4y ago
    The short preface is a good point. Maybe it could even get expanded in more dynamic elements. Basically a short recap with the ability to quickly dive in deeper if interested, so everyone can choose their level of detail, or glance over it, and only drill down if something stands out to them. I'll need to see whether our systems supports it.
- mikrl 4y ago
  Every IM I send has an immense emotional toll for some reason. Everyone is overworked and you’re another distraction, you feel like a giant asshole and then project that they’re a giant asshole too until you enter the emotional doom spiral. In person or on video flows so much more nicely because you can see the effect of interaction and be cordial to each other without the paranoia and dread setting in.
  - luckylion 4y ago
    Yeah, that's a bonus level of complexity, especially when you're reporting directly to someone you know probably has way more important stuff to do but you need a decision from their level about how to approach a certain issue that is constrained mostly by business.
deleted 4y ago
[deleted]
ChrisMarshallNY 4y ago
I think that short-form writing is important (I tend to prolix, so it's not my strongest point). I was always told that any proposal or explanation that is to land on the desk of a VP or higher (most companies, but the one I was in, was General Manager, or higher), needed to be a maximum length of one page, and not dense text. I have written a lot, over my life, but I tend to write fairly long pieces[0]. This has meant that I go fairly long periods, without writing, as I get involved in a project (like right now). I've recently started a new series, entitled "shorties"[1], that will hold very brief writings. These seem (to me) to be woefully inadequate, but I'll get it. A good exercise, for me, was the idea of a "mini-saga."[2] [0] https://littlegreenviper.com/miscellany/ https://littlegreenviper.com/miscellany/ [1] https://littlegreenviper.com/series/shorties/ https://littlegreenviper.com/series/shorties/ [2] https://www.danpink.com/2005/05/mini-sagas-another-approach/ https://www.danpink.com/2005/05/mini-sagas-another-approach/
massung 4y ago
This has little to do w/ being a developer vs. being human. People joke about the programmer in a dark corner plugging away and never talking to others, but that's actually pretty rare. In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together. The truth is that people - regardless of discipline - generally all want the same things from their work: to work on something meaningful, to be productive, and to be recognized for that work (both output and input). That's pretty much it. If - as a leader - you can do those, you're going to generally have rather happy employees. When it comes to this article, the issue is that there are a lot of people who believe that documentation and effective communication ARE necessary, but that work ISN'T recognized, and (because it isn't recognized) steals time that could be spent being productive doing something that is. If you want effective communication, documentation, etc. at your workplace, it's incumbent on leadership to create that culture. Nurture it, get better at it themselves, and help those less eloquent to find their [written] voice.
- aliqot 4y ago
  I'm good at what I do and am most prolific when given a complex task and the time/space to do it. It's not about being a shut in, I just prefer to socialize about what you have planned for the weekend when I reach a stopping point.
- maksimur 4y ago
  There are developers who have no choice but to work alone, but they socialize and collaborate otherwise. No matter what they do, a person talking over them is enough to make it impossible to focus on the task at hand, to think, even.
- wruza 4y ago
  People joke about the programmer in a dark corner plugging away and never talking to others, but that's actually pretty rare. In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together. These two sentences are not mutually exclusive. I love to discuss with professionals or hobbyists things that overlap with my own interests or profession. Or drink and joke with them, iow feel close. But put me in a pretty common group whose best interest are: shallow travel, second order or empty talks, etc - and I will plug away immediately, because telling them what they even laugh about is so boring would be rude.
dglass 4y ago
Some really good advice in the article, and I like the examples too. I agree with the author that communicating effectively is an important skill in a developer's tool box, but the article only covers written communication. In reality, effective communication involves speaking and listening skills as well. These skills are important enough for developers that I wrote a whole chapter on communicating effectively in my book[0]. Here are a few more points I think are helpful: * Communicating isn't just saying something. People might not understand your ideas, or they may interpret what you're trying to say in a different way. Sometimes you need to repeat yourself in order to drive your point across, and you may need to communicate your idea in multiple ways for people to really understand what you're trying to say. * If possible, try not to communicate through other people. Don't ask Tim to ask Alanna to do a favor or a task that you need to get done. It may feel like good delegation, but the more hops your message takes before it reaches its destination, the more chances for the message to get distorted, like a game of telephone. Try to communicate your message directly to the intended person if you can. Sometimes this isn't possible and you need to communicate through other people though. * Understand the audience you're communicating with. Are they technical? Then it's okay to use technical jargon and concepts. Are they not technical? Try to use more common terms and phrases. You may need to come up with examples and similes so it's easier for them to understand something that's technical or abstract. * Clear writing is critical in code reviews. If you think a line or block of code needs to be changed, explain why in the code review, don't just say it's wrong and it needs to be changed—that's not helpful. Especially with younger engineers that could benefit from understanding why their code could be improved. * If conversations turn in to long discussions on a code review, move the discussion to a video call or in person conversation. No one wants to follow a thread where two developers are arguing about whether something is right or wrong. Settle the disagreement outside of the code review. * You'll be writing a lot of technical requirements in your project management system as you get more experienced and lead more projects and features. What you write in the ticket won't always get interpreted exactly how you think it will, so try to write as clear and thoroughly as possible when describing what needs to be done. Sometimes you may need to describe how it needs to be done as well if you'd like it done a specific way. [0]: https://www.holloway.com/g/junior-to-senior/sections/how-to-communicate-more-effectively?ruid=6b3e0344-c60a-42c4-af5d-d7b168992127&utm_source=share_section_link&vip_code=FRIENDS https://www.holloway.com/g/junior-to-senior/sections/how-to-...
javier_e06 4y ago
Developers: Are short on time. Are misunderstood/alienated by corporate. Are bullied by The Firehose (Dev cycle). So, how can they effectively communicate? By keeping the Stable Release Humming.
- kayodelycaon 4y ago
  Add in it's basically impossible to get anyone in the company to reply to a comment on a ticket or read an email...
thundergolfer 4y ago
Last year wrote a technical writing advice checklist for engineers called How to ask for help in Slack: https://thundergolfer.com/communication/slack/2021/02/24/how-to-ask-for-help-in-slack/ https://thundergolfer.com/communication/slack/2021/02/24/how.... I was at Canva, a fast growing company adding 500 engineers a year, and the tenured engineers were getting hit with a lot of questions and help requests. I thought about this list a lot, and believe that maintaining adherence to all 10 checklist items will dramatically improve your technical communication in chat apps. For advice on writing long form communications, my absolute favorite resource is LEADERSHIP LAB: Writing Beyond the Academy[1]. This lecture will cleanse you of all the bad writing ideas you picked up in 12+ years of schooling, and show you actually how to think about professional writing. I've watched it about 4-5 times. 1. https://www.youtube.com/watch?v=aFwVf5a3pZM https://www.youtube.com/watch?v=aFwVf5a3pZM
- galoisscobi 4y ago
  This is an excellent guide. Thank you for taking the time to write it. I wish I had something like this when I started out in tech but helpful people early on taught me about not sending screenshots and sent a link to the XY problem explainer page.
  - thundergolfer 4y ago
    Thanks :) I hoped to turn my petty Slack frustrations into a helpful bit of shareable guidance.
- TillE 4y ago
  The problem with stuff like this (or ESR's How To Ask Questions The Smart Way) is that they only really get through to the people who care enough to want to improve themselves and their interactions, which is probably like 1%. Maybe it's easier if they're employees. But my overwhelming experience out there in the wild is that people ask terrible questions which can't be answered, because they put zero effort into anything.
  - thundergolfer 4y ago
madsbuch 4y ago
I have experience that suggests the contrary of his suggestions. Working in a remote culture, often we can spend too much time writing things out and in turn reading things that are irrelevant. I would propose a more progressive framework: Start with the short message without any context. If needed, make a new message with all the context. As an example I have a couple of times asked for help where a response would list the pros and cons of "REST" and I would have to spend too much attention reading it. Alternatively the following would have been perfect: > X is hard to do in Elixir, any ideas? < Defer it to our Next frontend. It is easy to do in JavaScript > Thanks!
- onion2k 4y ago
  The problem with opening with "> X is hard to do in Elixir, any ideas?" is that it shuts down any conversation about X. You've decided it's hard, but what if you're wrong? What if you could avoid X entirely by doing Y? What if the context around X makes it also hard to do in Next? Adding a little bit of context really helps open conversations.
  - Jensson 4y ago
    It is the opposite, being wrong is a really great way to start a conversation, people are really eager to correct mistakes.
    - squeaky-clean 4y ago
      The ol' Barrens Chat Law from WoW. Need to find Mankrik's Wife for that level 20 quest? Don't ask "Where is Mankrik's Wife?" instead say "If anyone is looking for Mankrik's Wife I found her by the auction house in Ratchet" and watch 25 players immediately respond that you're wrong and the real location is X. On a more serious note, while this works it can backfire if someone follows the wrong info too far, and it can make you look clueless if done too much. If you need to do this, I feel the best way is to also phrase it as a question but leading towards the incorrect answer. Something like "I've been trying to get X working in Elixir but keep getting errors. It looks like [library] doesn't support [feature]?"
benjaminmaccini 4y ago
This was a great read and conscious of the nuances to effective writing. Articles like these tend to have a "write this way NOT this other way" mentality. To paraphrase a comment I saw somewhere regarding code optimization: "Given enough time most code can be optimized quite a lot". The same can be said about writing. The audience, the topic, and the intended outcome make for a complex optimization problem that, as the author touches on, can eat up a ton of time. The PR comment example is perfect. The initial comment (on the lefthand side) works. *It does the job*, however when the author is placed in a different context (audience and intent), the comment on the right becomes more optimal. It also took 5x the amount of time to write up. I feel as though knowing the tradeoffs and managing your own time seems to be half the battle when it comes to communicating. My additional advice for devs is; get honest feedback on your writing (slack messages, design documents and everything in between) so that you can learn best what works with whom.
- withinboredom 4y ago
  I think a lot of this is your “intended audience’s tastes.” I’ve worked with people who will literally write you a book for every reply. The conversation was so incredibly dense you had to spend a long time just to figure out the point if there is even one to begin with.
D13Fd 4y ago
This is a great article with nice examples, and I like the "high resolution" vs. "low resolution" concept. But it leaves off the other side of the equation: know your audience. If your audience wants to read a long, detailed communication, then that's great and you should write a "high resolution" message. If your audience has little time available and no real need to know the details, then the "low resolution" message is much more effective. The real trick is learning how to pack exactly what the reader needs to know into a "low resolution" message.
- phinullfermata 4y ago
  Someone who doesn't care about the detail can and will stop reading. It's important to get your main point across early because of this fact. The inclusion of detail is helpful but it needs to be in the right place. I think this is why traditional business writing evolved to have an order like summary, recommendation, then supporting evidence. If you've written things well you can get the best of both worlds. I noticed this in the author's review example. The first paragraph gets a reasonably high resolution description of the problem, then the detail follows in the next paragraphs.
  - squeaky-clean 4y ago
    Basically the idea of inverted pyramid from journalism. Start with the necessary but minimal amount information up front. Then expand the details in subsequent sentences, the further in you get the more specific and granular you get. If someone feels they've gotten all the information they need they should be able to stop reading at that point.
  - D13Fd 4y ago
    I still disagree. Sure, you can get your main point across and then offer extra detail. But the extra detail is often detrimental in that your reader probably isn’t comfortable stopping before they read it. To be clear, I’m talking about business communications here (as was the article), not other kinds of writing. In my field, at least, this is a fundamental concept that differentiates some of the best communicators.
commandlinefan 4y ago
> The examples on the right, on the other hand, try to make the reader do less work, even though it is more effort for the writer Ironically, these are perfect examples of the sort of thing that developers think is better but actually turn out to be worse. I thought the same thing as the author, early on - the more detail I can cram into each message the better. What I've found, though, is that most people actually interpret that as hostility and prefer a short, quick overview followed by more detail when asked.
- sokoloff 4y ago
  The ones at the top of the blog post? The ones on the right are better for nearly every case I can think of. "what is 'it'?", "who is 'her'?", and "'not working properly' how?" are not the type of detail questions that people generally want to have to ask ever. (maybe the third is sometimes OK)
  - commandlinefan 4y ago
    Yep, that's exactly how human communication ought to work, and the world would be infinitely better if it did. But it doesn't, actually.
    - macintux 4y ago
      I have often been frustrated that my attempts to communicate clearly have failed, but I choose to believe that it’s my fault as a writer, not their fault as a reader. The alternative is being a jaded, negative person who is unpleasant to work with. It’s too easy, too lazy, to fall into that trap.
      - travisjungroth 4y ago
        Are you disagreeing with their conclusion or just the vibe? You can do both: believe things would be better with some global change, and also accept that won’t happen and do your best with how things are.
- 4y ago
451mov 4y ago
> Communicating effectively as an engineer means empathically increasing the resolution of your writing. What does that even mean?...
- lordswork 4y ago
  To communicate technical concepts effectively, think harder about what may be unclear or misunderstood by the recipient(s) and take the time to address those ambiguities preemptively.
kayodelycaon 4y ago
One of the issues with the effective communication listed is it takes a lot more effort. It can take me up to an hour to get all of my thoughts into words organized for easy understanding. But I'm usually dealing with things much more complicated and detailed that a REST api.
BurningFrog 4y ago
> Writing messages on Slack isn’t what engineers get paid for This is wrong. If you disagree, stop writing messages, and see how long you keep getting paid.
jmartrican 4y ago
The image on this article looks amazing. And it was AI generated. I would not mind seeing art like that in my living room.
BurningFrog 4y ago
Here is my competing take: The biggest problem I see in developer communication is what I call the "assumed context" problem. As in, you talk/write to people as if they know all about your code, except the detail being discussed. In reality, they usually have much less detailed understanding, and you're making no sense to them. I'm pretty sure this is related to people "on the spectrum" often having low "theory of mind" capabilities. People without that will just assume people know what they know, and proceed to fail at communicating with those who don't. It also makes it easy to think of those who don't know what is obvious to you as idiots. The workaround, if you want to communicate with the idiots surrounding you, is to start conversations by fact finding. The question "so how much do you know about the flurbigator system?" can help.
- DannyBee 4y ago
  I generally agree with this - the first part of any effective communication is to see where you and the other person/people are starting from. Only then can you decide how to try to communicate the rest.
- peteradio 4y ago
  Alternatively, why is someone who doesn't know the product directing its design without asking appropriate questions on their end?
- deleted 4y ago
  [deleted]
- taude 4y ago
  I think you're "assumed context" problem actually has another term called "Curse of Knowledge" [1] (which I believe it's much more known as). There's a ton of strategies that have been written about it. Just adding this term here for people who want to search for strategies on how to work around this. It comes into play in all forms of communication, written, verbal, Slack, etc... [1] https://en.wikipedia.org/wiki/Curse_of_knowledge https://en.wikipedia.org/wiki/Curse_of_knowledge
  - 4y ago
strunz 4y ago
Step 1: Don't use a gigantic header and cover image which takes no less than 3 full scrolls of a mousewheel to get to the content.
SevenNation 4y ago
> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Instant messaging tools are seen more as a necessary evil to get work done in a team than anything else. Because of this dynamic, there is a tendency to elide details or cut messages short, sometimes at the expense of legibility. The article is long on tips for individual media without explaining why you'd use one over the other. Digital communication encompasses a wide spectrum of media, each with its best use: - realtime/recorded text (Slack, GitHub issue, README, Comment, etc.); - recorded graphics/text (PowerPoint) - realtime/recorded voice (voicemail, phone); - realtime/recorded video (Zoom, YouTube). The most important question before you use any one of them is: why this medium and not one of the others? Even the right message created well will flop if sent across the wrong medium.
kapitanjakc 4y ago
In my own brain I've created 3 different categories :- Others, Developers, Management. I find it easier to explain stuff to other people by giving context from their field For example to someone in food industry I'd say, frontend is like how you present your food at the table and back-end is like the kitchen where food is prepared. To people in development what I've learnt is that you've got to find the right balance, can't dumb it down a lot or can't switch it up, always in the middle. Management will understand 3 things : Excel, PowerPoint, Money. That takes care of 90% of my conversation.
- booleandilemma 4y ago
  What makes you think you know anything about the food industry, or the context where people are coming from, in general?
  - kapitanjakc 4y ago
    In general I don't, but usually when meeting someone new we introduce each other right? Otherwise if the person is someone you know already there's a better chance that you know what is their line of work. Also It's more of a analogy thing Explain stuff to them in their language. But while writing stuff we don't know who's going to read it, so a general analogy, a bit tech stuff and few visual stuff all of these can be used.
decaffjoe 4y ago
Always worth it to spend 2-3x the time authoring a message with explicit context since it's going to save every reader 2-3x the time figuring out what you're talking about.
chiefalchemist 4y ago
> It's not about you, though.. It's about them. Ironically (given the context), he buried the lede. That aside, if you're interested in raising your comms flag, I recently finished "Smart Brevity". As a solution, it's not a panacea for all use cases. Still, it's a quick and useful read. Simple but effective. https://www.thriftbooks.com/w/smart-brevity-write-less-say-more-get-heard/34185851/?resultid=d22fe885-bd5e-4105-b5df-74b939a79620#edition=61265924&idiq=52276022 https://www.thriftbooks.com/w/smart-brevity-write-less-say-m... I'd also recommend "Words That Work" by Frank Luntz. Chapter 1 is all you need. The rest is simply the lessons from Chapter 1 in practice. https://www.thriftbooks.com/w/words-that-work-its-not-what-you-say-its-what-people-hear_frank-luntz/251558/?resultid=2805995f-7cd0-4c38-a44b-6f93da6b42a9#edition=4919560&idiq=3895357 https://www.thriftbooks.com/w/words-that-work-its-not-what-y...
azangru 4y ago
My biggest communication problem as a developer at the moment is with the designer. It is as if we were speaking different languages — and I am not just talking about the jargon such as "persistent storage" or "api" on one side vs "kerning, tracking & leading" on the other side. No, it's the fundamentally different ways of thinking, and inability to pick up on what's obvious for the other side (as a developer, I, naturally, blame the designer for all these difficulties in communication; but I am sure that she blames me). I am both amused and annoyed at this; not sure which more.
zackmorris 4y ago
I tend to write diatribes that nobody will ever read, so I've switched to writing a quip first, with details below in inverted pyramid style so that the reader doesn't have to ask for more information. --- I usually start with a: # Solution: With links to any tickets/jobs/etc. For example, the inverted pyramid puts the most important info first: https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) Then I'll put any relevant notes and commands that I refer to as: # Discovery: ``` # in a big block of literate programming (Mac only, try `curl -ks` to skip SSL checks if the clock's wrong in your shell) curl -s https://en.wikipedia.org/wiki/Literate_programming | textutil -convert txt -stdin -stdout ``` So that people in a hurry can skip the parts they don't need. Edit: I edited this a lot, might need to refresh
- booleandilemma 4y ago
  This is how newspaper articles are written. Critical details up front followed by the extra info at the bottom.
jlos 4y ago
It is just as difficult to learn how communicate technical material to peers and lay audiences as it is to learn the technical material itself. Before becoming a dev I spent almost a decade training and involved in Christian ministry, a surprisingly technical field. It's hammered into your head you need to balance technical excellence and impactful communication to lay-audiences. You can't sacrifice either. I don't think devs are given that perspective. Some observations I've had - 'Dev in a cave' do exist though, are more prevalent in software/engineering that elsewhere. They aren't the majority, but you will interact with them if you interact with developers/engineers. - Computer science and engineerings curriculums absolutely do not prioritize good communication. Even if devs come from informal backgrounds, they are in the same boat of needing to learn how to communicate technical material. - Even if most devs understand communication is important, they don't seem to appreciate how much work it takes, and are not likely aware of the ways to develop those skills. - The only real exceptions I've found to the above are people like myself who've come into development from some humanities discipline (philosophy, history, english, etc). Greek, Hebrew, Latin, and maybe a bit of German is the baseline for a theologian worth their salt. Include with that a working knowledge of history (Greco-Roman, Ancient Near Eastern, Mediaval, Reformation/Renaissance era, and Modern), philsophy, linguistics, and literature. These are of course extras on top of the primary area of study in biblical studies, systematic theology, pastoral theology, and historical theology.
jonnycomputer 4y ago
I'm not sure their example of "improved" short-form messaging improves things much. In some ways its worse. We're all being overwhelmed with information, and often the thing we want to know is: is this relevant to me, and what is the gist. The terser the better. For what it's worth, I sometimes go with something like: Update on foobar.py bug: - Script was not updating last-name column in person table - Notified Sarah, and Sarah will push fix soon Details: Blah blah blah, if you aren't interested in all these details, don't read this. But super useful if you need it.
- Brystephor 4y ago
  > I'm not sure their example of "improved" short-form messaging improves things much The bad short form message is bad because 1) it's ambiguous and 2) it has a short lifespan. By lifespan, I mean the time that a message can be read and can be useful. Using terms such as "it" and "she" leave a lot of ambiguity. If you read the message 7 days later, 1 day later, maybe even an hour later, all context of what "it" is and who "her" is could be lost. Using names instead of "it"/"her" means you can read the message 24 hours later, maybe even a week later and still understand what it was, or at least it gives you more information to figure out what the context was. In short: I think the improved message is significantly better than the first. > The terser the better. In general I agree with this. I have no evidence but I'd bet some people prefer the conversational message over the status update. Again, it depends on the context. If it's a status update, make it a status update. If it's a conversation, let it be one.
witnesser2 4y ago
I think some epic SE failures, the DOJ LE should get involved. So the engineers' habit of providing details in written materials is indisputable potential forensic self defense. Like the egg Greg in succession, he has a filmsy shell, but it protects, serves when needed. My first civil engineering trainings, our department head she repeatedly stated and gave examples that 'you may go to jail if you don't follow the design rules and it failed' like this. There is nothing called communication in engineer's world. That means plane fell, bridge collapse -- they are negotiable. This is a community talk of opinions.
- canadianwriter 4y ago
  ...does this make sense. These seem like words that should go together but I can't grok what is being said.
squeaky-clean 4y ago
This comment only applies to bug report / support request issues, but my personal rules that seem to work well are: What happened? What did I expect to happen? What actions did I do to make it happen, or if it's an automated task then mention that. Then list any errors/logs/etc I've already found that I think are directly relevant. Then what I've already tried to fix it (if applicable). Then what I think should be tried. Then any additional logs/errors/etc that I'm not sure are relevant, but also that I'm not sure are irrelevant. So something like "Hey I'm trying to deploy X but getting a ModuleNotFoundError for Y in the Jenkins build step. It builds successfully on my local machine. I'm running make deploy-dev and getting the error. Running make deploy-local gives no error. This is the error [codeblock quote of the relevant error line]. Here is a link to the Jenkins output for my most recent build [link] I've added the module to setup.py and I see Jenkins says that it installed the module [quote of Jenkins output line]. Maybe clearing the Jenkins cache would help? This is probably not related but I see Jenkins also logged a JVM Heap Memory warning at the start of the run."
itsmemattchung 4y ago
I'd argue that the most important thing to consider when trying to communicate effectively is this: know your audience. One "low resolution" (using author's terminology) sentence might actually communicate more effectively than a "high resolution" one, given the right context and right audience. Similarly, a "high resolution" text over explain and perhaps even offend the reader. In short, it depends.
jb3689 4y ago
Writing too much is just as bad as writing too little. It really depends on context. If I write you an essay and the salient points are buried, that’s even worse than being short and lacking clarity. At least in the latter case the receiver can ask for clarification
dannas 4y ago
=== Cut needless words === The article references Covingtons How to Write more Clearly, Think More Clearly [...] Powerpoint presentation [1]. I highly recommend it! A fun part in that presentation is when Covington, in a series of steps, revises this sentence... “One of the best things you can do for yourself to improve your writing is to learn how to cut out words that are not necessary.” ..Into this one: “To improve your writing, cut out unnecessary words.” OPs article calls for more words to provide context. But by revising you can often cut the length in half. [1] https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf
AtNightWeCode 4y ago
Agree with most of it. But I think the response to the PR was unnecessary. I would have pointed out that it does not work and told the person to remove it or fix it.
kebman 4y ago
Here I am, the copywriter slash programmer slash musician. Yes, I play the keyboard.
oxff 4y ago
Learn to adjust your abstraction and resolution to the intended target audience. That's about it.
rib3ye 4y ago
In short, part of your job is spending 3-4x more time thinking about how to write for the human psychology computer.
tristor 4y ago
As someone who went from engineering to product management, partly due to having developed a skill of communicating effectively in writing and in speech, I would suggest perhaps the most important part of communicating effectively is storytelling. If what you are sharing does not have a clear and obvious narrative arc, people are going to disengage quickly. This is not necessary for short bursts of information in a high-context environment, but any time you need to level set and share context before communicating the critical information, you should do so in story fashion. If you want to level up your technical communication, I'd highly recommend taking classes in creative writing, participating in things like NaNoWriMo, or taking a class in improv comedy/theater. All of these things emphasize construction of narrative arcs and how to draw people through a story, which are essential communication skills. This gets more important the farther up the chain of command in a company you are communicating with.
- wcedmisten 4y ago
  I recently watched Kelsey Hightower's Strange Loop talk on "The Secure Software Supply Chain", which incorporates a humorous narrative about deploying code found on a flash drive in a coffee shop. I think the talk was especially captivating because of that. I'm trying to incorporate that narrative aspect into my own demos and presentations now. https://m.youtube.com/watch?v=JC-xCXcyNXI https://m.youtube.com/watch?v=JC-xCXcyNXI
- zwkrt 4y ago
  Completely agree, although I don't think that people need to be better creative writers to be better at creating narrative arcs. For work, your narrative arc is normally solved if you are understanding (1) the relationship between you and your audience, (2) what you want, and (3) why your audience should care. If you communicate those things, the narrative should be crystal clear. That depends heavily on the context. "Hi, I'm from a team from far away in company land (1). I've been having an issue with your service for the last few weeks because it seemingly drops connections sometimes. I looked at your metrics and I see that this is happening to other clients as well. This issue is stopping us from deploying a change to the UI that we promised customers would go out next week (2). Can you help me debug from your side? (3)" "Hey boss (1). I think that I need more support on this project (2a). We originally thought it would be easy to refactor a widget into a widgetFactory, but after I investigated it widgetFactories will require a schema migration (3). I think Sarah is really good with those, can I ask her to work on this with me (2b)? "Apache upgrade production outage thread (123)"
karmelapple 4y ago
> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Perhaps I'm being picky, but... that's also not what engineers get paid for, either. I think engineers get paid to do things that solve problems. Sometimes that involves writing code, but sometimes it absolutely involves writing a Slack message, having a call, or just thinking a little more. A Slack message might be, "Got a minute to chat?" to start a voice call that will clarify some requirement that's been bogged down in a quagmire of too much writing or conflicting ideas. Requirements are clarified, maybe not a single line of code is needed to be written, thanks to a better understanding of the customer's desires. A Slack message might ask, "Does this change work instead?" with an image attached of a simpler approach. I wouldn't typically respond to one line from a blog post, but since this was up so high in the post, I felt I needed to gently encourage a little rewrite of this sentence :)
- deleted 4y ago
  [deleted]
- deleted 4y ago
  [deleted]
mcculley 4y ago
These points are generally true to anyone who ever has to write an email or text message as part of a job. This could be generalized to "How to communicate effectively as a knowledge worker".
raydiatian 4y ago
> empathically increasing the resolution of your writing I find this to be obnoxious and nonsensical, which, in an article about communicating effectively, is ironic.
datavirtue 4y ago
This reads like a bullet list of things you should have picked up in the five-to-ten English/writing classes you took in high-school and college.
analog31 4y ago
>>>> Writing effectively is a superpower, there is no denying it. As a software engineer, you write a lot. Most of the writing you do is for computers. Businesses, however, consist of people. Someone wrote that code is meant to be read by people, and secondly, by the computer. Lack of writing skill could spell trouble for the quality of the code, should anybody need to read it, days or months later.
stack_framer 4y ago
I think we overlook wordiness too often! In fact, each "good" example in TFA can be shortened without losing context: Good: "I checked the foobar.py script and told Sarah that there was a bug related to updating the users table in SQL — the script does not seem to update the last name column." Better: "I found a bug in foobar.py and told Sarah it's not updating the last name column in the users table." Good: "Hi team, the email sending worker keeps crashing with the following exception. I've tried re-running, clearing the cache, re-installing dependencies. Can I get a hand?" Better: "The email sending worker keeps crashing with the exception below. I reran it, cleared the cache, and reinstalled dependencies. Can I get a hand?" Good: "The resource defines two routes, but the GET handler can only handle one of those — the one without any path params. I can technically make a request GET /api/foobar/123/456 and have the app crash with a 500 because there is a route but the handler doesn't take any params. Roughly speaking, there are two "types" of resource endpoints — list and singular. List type resource endpoints handle - getting a list of resources: GET /things - creating a new resource: POST /things Singular type resource endpoints handle - getting a single resource: GET /things/123 - updating a single resource: PATCH /things/123 - deleting a single resource: DELETE /things/123 To handle all cases properly, you need two resources: ... " Better: "The resource defines two routes but the GET handler can't take path params, so a request to GET /api/foobar/123/456 crashes the app with a 500. There are two "types" of resource endpoints: List: - get a list of resources: GET /things - create a resource: POST /things Singular: - get one resource: GET /things/123 - update one resource: PATCH /things/123 - delete one resource: DELETE /things/123 So you need two resources: ... "
- pnt12 4y ago
  You can have both of best worlds using BLUF: bottom line up front. I didn't read the code because it's too early to debug someone else's code, but here's an example: These endpoints break REST conventions and will be harder to understand and maintain. The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>. I find it useful for two reasons: - maybe you parse the first paragraph and you have enough context to act, so you skip the second - or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details
maxrev17 4y ago
People who understand the problems tend to be disinterested in those being paid to 'manage' them. I think that's the foundation for most of the issues.
SinParadise 4y ago
The first order positive and second order negative speaks to me. I prioritize the former over latter unless I am creating a demo/presentation of some kind. I still see defaulting to prioritizing second order effect as a waste of effort majority of the time.
aymar_99 4y ago
One thing i can share from my experience is, some people communicate poorly because of laziness. In this case, Even if the vague communication is understandable to you since you are aware of the dev's current WIP, pretend you don't understand and nudge the developmer to add more details for the context as necessary. For example let's say your team has 5 services. The developer pings you : when starting the service i am facing this exception, tried different ways couldn't figure out, can you please help? . Questions : Which service is he trying to start? Which machine is he trying to start?(local/virtual). He probably doesn't mention these details because he thinks you must be aware of what he is working on. Even if you know the same, you can ask these questions and ask to mention such infos going forward to improve their communication. The idea is to communicate clearly as with any developer and not to take things for granted due to laziness in typing the relevant details.
deleted 4y ago
[deleted]

549 points by karls 4y ago

Very good old thread on HN on similar lines (Ask HN: How to speak like a leader, not like an engineer?) https://news.ycombinator.com/item?id=19349676 https://news.ycombinator.com/item?id=19349676

ramilefu 4y ago

The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. I think this is the origin for much of the friction we experience in collaboration and documentation. It’s easy to build something, ship it, and move on. That’s the dream we are sold as well: changing the world, one line of code at a time, from our basements. I would love to see more focus on writing in our industry. Unfortunately, I haven’t experienced much improvement here in the last decade of working in the industry, across several organizations. The writers among us are quite the minority.

scruple 4y ago
> Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. They have to write the code because that's what is demanded of them. If management would prioritize communication they would get more of it.
batesy 4y ago
Seems like a pretty significant opportunity to level up for those willing?
- ramilefu 4y ago
  Certainly. I’ve leaned into it, when given the chance. As the author writes, it definitely makes you stand out, if you are willing.
- soneca 4y ago
  It definitely helped me a lot in my career. It is hard to single out its impact, as good writing also help me demonstrate other non-technical qualities like diligence, trust, problem-solving. But I might take a guess and say that about 30% of my salary is due to good written communication skills
- KptMarchewa 4y ago
  On the contrary, a lot of businesses punish it.
ngrost24 4y ago
Personal opinion or anecdata: Is it possible that communication is "detested" because it's not valued within the developer group? Many times, when someone speaks of a 10x software engineer, the gut feeling is of someone that provides the output (measurable in code) of 10 developers, not that he's able to have an impact in the organization through communication as 10 developers (breaking silo-s, syncing teams, etc), although this might be closer to the truth and what the duties of some staff and principal level developers includes. In addition, rarely communication is valued within the companies where we work. Most aspects of documentation, whether vocal or written, are hard to measure and as such are ignored when an evaluation of the "worth" of an IC is done. Personally, I think communication is relevant, but I also think that it's hard for developers to resist the sculpting that companies deliver to the employees on what is relevant in this field.
- xbfjvusb6 4y ago
  This. I can tell HR, my lead and skip about how good my communication, soft skills and team work have been this year but come comp review they don't give a crapola about any of that. All they look at is how many sloc I've shipped.
  - scarface74 4y ago
    For context: I never really cared about yearly reviews or raises at my job before my current job. I knew they were going to be mostly shit anyway and that I was better off job hopping every couple of years to get a “raise”. Which I did six times between 2008 and 2020 after staying at my second job 9 years and getting 3% raises and seeing the bonus drop. That being said, the only formal raise/promotion process i know about are at tech companies. Promotions are based on “scope” and “impact” and not how well you code. The only time “coding well” comes into play is going from junior or mid. Even the interviews that determine your leveling is based on behavioral interviews and system design. I couldn’t interview for my next job and all I could put on my resume is “I wrote a lot of code”
  - karmelapple 4y ago
    I'm fascinated: does your company/manager truly track SLOC and promote based on that? Or is SLOC here more of a proxy for "features shipped"? Because if this is what's happening, I'd encourage two changes: 1. Communicate differently to HR, lead, and skip - either use different approaches of documentation, or point out different aspects of your contributions 2. If trying various different approaches don't work... leave. For communicating differently - I used to work at a large company, and our yearly reviews had places to capture accomplishments. That was a broad topic: it wasn't just features built, bugs fixed or identified, etc. It would also be totally appropriate to put ways you saved money or time on various initiatives, and I would frequently put down items like this. How do you communicate "how good" your "communication, soft skills, and team work have been this year"?
PragmaticPulp 4y ago
> The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. I wouldn’t say most developers fit this description, but there are a lot of people out there who embody this isolationist working style. Some times they can be fit into a team’s structure if you have a constant stream of small tasks that really can fit into a queue of fully-contained tickets and the person is capable of self-managing and delivering good work at a reasonable rate. However, that’s a lot of conditions that many people just don’t meet. Often what ends up happening is that the rest of the team and the manager have to put in extra effort to work around the person’s personality, which slowly drags everyone else down. That’s why it’s so important to screen for proper match during the interview process. I’ve seen a decent number of candidates who performed great on interviews, but couldn’t even pretend to be friendly during any stage of the interview. Surprisingly, a lot of them even seem to take pride in their demeanor. I think there’s a romantic idea out there of coding mercenaries who show up, take paychecks in exchange for writing code in isolation until they feel like moving on. This mentality sounds great to people who dislike communicating or working with others, but it’s incompatible with any teamwork or any project that must scale beyond a single person. Most of the work I’ve been involved with has required teams and teamwork, so these people don’t really have a place in the team.
Multicomp 4y ago
> The writers among us are quite the minority. Tell me about it. I'm lucky enough to have a supportive manager when I try to define my teams fitness functions, but getting the rest of the team to engage is an exercise in patience testing on all sides. They don't see the value in writing useless essays, shouldn't self documenting code be enough? I don't see the value in skipping high resolution communication up front so we can all waste time reworking the same problem for the 5th time that month because we forgot what we decided the 4th time we worked on it.
- Nextgrid 4y ago
  One suggestion I would add is to make it easy to do the things you ask for. You're already having trouble getting your team to do it, the last thing you want is for them to have to suffer through shitty tooling to do so (and give them another excuse to skip doing it). Having documentation in anything Atlassian-branded (or similar garbage) is a no-no for example. That's one of the few cases where I would completely understand & support a developer outright refusing to do it. Writing essays might not be everyone's cup of tea (personally I'm fine with it as long as it will be useful and will not just rot away in darkness forever), but it's manageable with good tools. But if I have to wade through molasses like Confluence, I'd totally understand why nobody wants to engage and wouldn't even be mad at them. I'm generally not the kind of developer who hides in a cave, but as time goes on I understand them more and more - it turns out a lot of what these "cave" developers don't like involves absolutely terrible tooling that actually regressed over time (despite processing power and system resources constantly increasing).
- P5fRxh5kUvp2th 4y ago
  document decisions and move on, why are you asking your team to write essays? Companies bitch about the performance of developers then ask them to do things like this. What's worse is when companies give developers all the responsibility and none of the control.
  - skydhash 4y ago
    Very much this. I like to write my documentation in Markdown because it allows me to be fast, while still having some structures. Then I paste the draft in Google Docs when I want to share and have people comment on it. Tooling matters and if I'm the one doing something, I want to actually choose how I'm doing it.
Jensson 4y ago
Developers hates communication since developers gets blamed for all communication problems even when they aren't at fault, until that changes most developers will hate it and refuse to do it since they got burned.
throwawaysleep 4y ago
> Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion. And are also career incoherent and not valued. I get measured on points per sprint. Documentation, customers, and PR review does not help me hit key metrics, which is why I do all I can to get out of it, including being bad at it so that I am not asked to do it anymore. Nobody has ever scolded me or had a performance meeting with me about botching reviews, docs, or knowledge sharing. I am never asked about these in interviews either. The questions are all technical or generic "how do you handle disagreement with a colleague?"
FoomFries 4y ago
I would love to hear some resources for improving. Separating the chaff from the wheat on resources is always difficult for the layman, similar to learning an instrument for the first time. Most things I find on improving writing is related to fiction, and other areas of improvement seem unnecessarily anecdotal or story driven.
hbrn 4y ago
Spot on. But it's not even about writing. Developers hate communication, in any form. Going remote made it much worse, there's even more ways to avoid communication or turning it async. The only remedy I found is actively forcing people to talk to each other, starting with yourself. Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you. Need a code review? Grab the reviewer and walk them through the parts that are hard to understand. Designing a big piece of architecture? Instead of writing a thorough design doc that nobody will read, build a rough diagram and share it with the team immediately, preferably on a call. Writing documentation? Ask your team members what they want to see in it. Yeah, it sucks to do all of that when you're an introvert. But it gets easier with time. And hopefully you can find joy in the fact that you are delivering value X times faster.
- skydhash 4y ago
  > The only remedy I found is actively forcing people to talk to each other, starting with yourself. That's not communication. That is forced socialization. There are things that are expressed more efficiently in spoken form, but the truth is that spoken words are ephemeral and the mechanism for storing and retrieving them are cumbersome. I like written communication, it forces you to be more structured in your thinking. And most importantly. It does not require another person to be actually present for this to happen. > Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you. I strongly believe that a review that can be done in a slack hurdle in 15 minutes can be done async in less. And there is the need to actually schedule for that hurdle. And in practice, every one of these hurdles will actually be surrounded by a period of non-productive time. Programming is thinking work. The actual coding, while visible, is the easiest part. We hate wasteful meetings because it contributes nothing to make thinking easier.
  - chrisweekly 4y ago
    Agreed; even further, the presence of even a small number of interrupts can disrupt the extended focus and context-building that are required to solve gnarly problems. See also pg's famous "Maker's schedule" post: http://www.paulgraham.com/makersschedule.html http://www.paulgraham.com/makersschedule.html
devonkim 4y ago
The issues I have are that developers tend to be bad at communicating even with each other. Communication as a discipline is a lot about meeting people where they are and this is difficult for basically everyone. The antagonistic attitude that developers seem to develop happen across almost every technical discipline whether it’s engineering or even trades. It may be even worse in trades given so much contact with the general public. If developers had to do customer support for their products as a rule you bet they’d get grumpy. However, I’d also say that interacting with the public probably makes most people in US retail grumpy, too. What I think I’m trying to say is that developers self-selecting out of things thinking they’re either not good at them or because they don’t like to do them is a bit of a luxury compared to most professions and many on the outside would look at that and feel there’s an attitude of arrogance and entitlement as such.
- frenchman99 4y ago
  > If developers had to do customer support for their products as a rule you bet they’d get grumpy. Do you have data to support this? I would love to do customer support from time to time to better understand the users of the product I work on as a developer. But that request has been denied to me many times, in multiple jobs. To get people to communicate better, inspire them to do so and have faith in them.
  - devonkim 4y ago
    The data I’m seeing is from studies showing that developers doing peripheral duties and getting interrupted is one of the biggest barriers to productivity and quality among developers rather than training, education, or even raw IQ. Specialization of roles along with the political realities of corporations means that fiefdoms and exclusions will happen to though.
    - frenchman99 4y ago
      It is perfectly possible to do customer support on a specific schedule so that it doesn't become an interruption though.
markrages 4y ago
Sometimes I get the feeling that many developers are functionally illiterate. (In the https://quoteinvestigator.com/2012/12/11/cannot-read/ https://quoteinvestigator.com/2012/12/11/cannot-read/ sense.) I can spend as much time as I like writing comments or design documentation or whitepapers or commit messages, but nobody reads it. Maybe they will set up a meeting for me to read it to them.
- justin_oaks 4y ago
  That's probably about right. But it's not isolated to developers. Most people skim or skip most instructions, documentation, warnings, etc. When I write documentation I hope that people will never talk to me because the information they need is already written down. But more often it's so I can redirect them to the documentation and implicitly require that they read it before they continue to talk to me. In other words, documentation doesn't usually prevent an interruption as much as it minimizes the interruption.

smileysteve 4y ago

The post begins with a preface about promotions for leadership from the Csuite. But I argue most Csuite and leaders are horrible at this too; I can't tell you how many all hands or emails I've been at where leaders use the abbreviations ELT, LT, ET, Csuite to refer to themselves -- and then use abbreviations for their move-the-needle projects and expect everyone in the room to know what they mean. Clear communication is great, especially in the remote world or when dealing with complex situations. But this isn't a trait that leaders have more than developers, and it's not a trait that particularly gets you outside the development track. Frankly, Ruby on Rails - and Rspec provide an example that developers should be very verbose -- in their method names, their file names, the description, background, context, and specific examples..

samwestdev 4y ago
> Frankly, Ruby on Rails - and Rspec provide an example that developers should be very verbose -- in their method names, their file names, the description, background, context, and specific examples.. Very interesting. Any practical example from said codebases?
- smileysteve 4y ago
  https://edgeguides.rubyonrails.org/active_record_basics.html#naming-conventions https://edgeguides.rubyonrails.org/active_record_basics.html... https://www.rubydoc.info/gems/rubocop-rspec/1.25.1/RuboCop/Cop/RSpec/ContextWording https://www.rubydoc.info/gems/rubocop-rspec/1.25.1/RuboCop/C...

bsenftner 4y ago

This is one of the more critical issues of our industry, of our entire society actually.

magicalhippo 4y ago

Glancing over the examples, I don't see anything that's particularly unique to us developers. Support, marketing, sales, the bosses, our customers, they could all improve their communication in the ways presented here. For me, learning how to construct simple proofs during my early math classes at uni really helped my writing. It made me pay a lot more attention to what I'm writing, like ensuring arguments are laid out in a more logical manner and that references are clear. Not saying I'm exceptionally good at it. But given that language was by far my weakest topic at school until then, I've since helped both my SO and my sister gain over a full grade point increase in college on hand-ins and similar, just by looking over what they've written and doing some minor tweaks like reordering sentences to ensure logical consistency in their arguments.

luckylion 4y ago

Judging the right amount of information is what I struggle with. It's easier to judge whether someone wants more details when you're talking to them. It's harder when you're responding to a comment or in a chat. When it's too little, you go back and forth. When it's too much nobody reads your novel. I tend to go into too much detail, so I'm learning go where I feel is adequate and then take a few steps back.

willjp 4y ago
I think it helps if you can preface your paragraph with a short summary. The reader then knows generally the scope of what you are trying to communicate, and the details become more approachable. That said, I’m pretty horrible at this balance as well, and often lean towards long form “walls of text” that eat office hours, then work OT to compensate.
- luckylion 4y ago
  The short preface is a good point. Maybe it could even get expanded in more dynamic elements. Basically a short recap with the ability to quickly dive in deeper if interested, so everyone can choose their level of detail, or glance over it, and only drill down if something stands out to them. I'll need to see whether our systems supports it.
mikrl 4y ago
Every IM I send has an immense emotional toll for some reason. Everyone is overworked and you’re another distraction, you feel like a giant asshole and then project that they’re a giant asshole too until you enter the emotional doom spiral. In person or on video flows so much more nicely because you can see the effect of interaction and be cordial to each other without the paranoia and dread setting in.
- luckylion 4y ago
  Yeah, that's a bonus level of complexity, especially when you're reporting directly to someone you know probably has way more important stuff to do but you need a decision from their level about how to approach a certain issue that is constrained mostly by business.

deleted 4y ago

[deleted]

ChrisMarshallNY 4y ago

I think that short-form writing is important (I tend to prolix, so it's not my strongest point). I was always told that any proposal or explanation that is to land on the desk of a VP or higher (most companies, but the one I was in, was General Manager, or higher), needed to be a maximum length of one page, and not dense text. I have written a lot, over my life, but I tend to write fairly long pieces[0]. This has meant that I go fairly long periods, without writing, as I get involved in a project (like right now). I've recently started a new series, entitled "shorties"[1], that will hold very brief writings. These seem (to me) to be woefully inadequate, but I'll get it. A good exercise, for me, was the idea of a "mini-saga."[2] [0] https://littlegreenviper.com/miscellany/ https://littlegreenviper.com/miscellany/ [1] https://littlegreenviper.com/series/shorties/ https://littlegreenviper.com/series/shorties/ [2] https://www.danpink.com/2005/05/mini-sagas-another-approach/ https://www.danpink.com/2005/05/mini-sagas-another-approach/

massung 4y ago

This has little to do w/ being a developer vs. being human. People joke about the programmer in a dark corner plugging away and never talking to others, but that's actually pretty rare. In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together. The truth is that people - regardless of discipline - generally all want the same things from their work: to work on something meaningful, to be productive, and to be recognized for that work (both output and input). That's pretty much it. If - as a leader - you can do those, you're going to generally have rather happy employees. When it comes to this article, the issue is that there are a lot of people who believe that documentation and effective communication ARE necessary, but that work ISN'T recognized, and (because it isn't recognized) steals time that could be spent being productive doing something that is. If you want effective communication, documentation, etc. at your workplace, it's incumbent on leadership to create that culture. Nurture it, get better at it themselves, and help those less eloquent to find their [written] voice.

aliqot 4y ago
I'm good at what I do and am most prolific when given a complex task and the time/space to do it. It's not about being a shut in, I just prefer to socialize about what you have planned for the weekend when I reach a stopping point.
maksimur 4y ago
There are developers who have no choice but to work alone, but they socialize and collaborate otherwise. No matter what they do, a person talking over them is enough to make it impossible to focus on the task at hand, to think, even.
wruza 4y ago
People joke about the programmer in a dark corner plugging away and never talking to others, but that's actually pretty rare. In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together. These two sentences are not mutually exclusive. I love to discuss with professionals or hobbyists things that overlap with my own interests or profession. Or drink and joke with them, iow feel close. But put me in a pretty common group whose best interest are: shallow travel, second order or empty talks, etc - and I will plug away immediately, because telling them what they even laugh about is so boring would be rude.

dglass 4y ago

Some really good advice in the article, and I like the examples too. I agree with the author that communicating effectively is an important skill in a developer's tool box, but the article only covers written communication. In reality, effective communication involves speaking and listening skills as well. These skills are important enough for developers that I wrote a whole chapter on communicating effectively in my book[0]. Here are a few more points I think are helpful: * Communicating isn't just saying something. People might not understand your ideas, or they may interpret what you're trying to say in a different way. Sometimes you need to repeat yourself in order to drive your point across, and you may need to communicate your idea in multiple ways for people to really understand what you're trying to say. * If possible, try not to communicate through other people. Don't ask Tim to ask Alanna to do a favor or a task that you need to get done. It may feel like good delegation, but the more hops your message takes before it reaches its destination, the more chances for the message to get distorted, like a game of telephone. Try to communicate your message directly to the intended person if you can. Sometimes this isn't possible and you need to communicate through other people though. * Understand the audience you're communicating with. Are they technical? Then it's okay to use technical jargon and concepts. Are they not technical? Try to use more common terms and phrases. You may need to come up with examples and similes so it's easier for them to understand something that's technical or abstract. * Clear writing is critical in code reviews. If you think a line or block of code needs to be changed, explain why in the code review, don't just say it's wrong and it needs to be changed—that's not helpful. Especially with younger engineers that could benefit from understanding why their code could be improved. * If conversations turn in to long discussions on a code review, move the discussion to a video call or in person conversation. No one wants to follow a thread where two developers are arguing about whether something is right or wrong. Settle the disagreement outside of the code review. * You'll be writing a lot of technical requirements in your project management system as you get more experienced and lead more projects and features. What you write in the ticket won't always get interpreted exactly how you think it will, so try to write as clear and thoroughly as possible when describing what needs to be done. Sometimes you may need to describe how it needs to be done as well if you'd like it done a specific way. [0]: https://www.holloway.com/g/junior-to-senior/sections/how-to-communicate-more-effectively?ruid=6b3e0344-c60a-42c4-af5d-d7b168992127&utm_source=share_section_link&vip_code=FRIENDS https://www.holloway.com/g/junior-to-senior/sections/how-to-...

javier_e06 4y ago

Developers: Are short on time. Are misunderstood/alienated by corporate. Are bullied by The Firehose (Dev cycle). So, how can they effectively communicate? By keeping the Stable Release Humming.

kayodelycaon 4y ago
Add in it's basically impossible to get anyone in the company to reply to a comment on a ticket or read an email...

thundergolfer 4y ago

Last year wrote a technical writing advice checklist for engineers called How to ask for help in Slack: https://thundergolfer.com/communication/slack/2021/02/24/how-to-ask-for-help-in-slack/ https://thundergolfer.com/communication/slack/2021/02/24/how.... I was at Canva, a fast growing company adding 500 engineers a year, and the tenured engineers were getting hit with a lot of questions and help requests. I thought about this list a lot, and believe that maintaining adherence to all 10 checklist items will dramatically improve your technical communication in chat apps. For advice on writing long form communications, my absolute favorite resource is LEADERSHIP LAB: Writing Beyond the Academy[1]. This lecture will cleanse you of all the bad writing ideas you picked up in 12+ years of schooling, and show you actually how to think about professional writing. I've watched it about 4-5 times. 1. https://www.youtube.com/watch?v=aFwVf5a3pZM https://www.youtube.com/watch?v=aFwVf5a3pZM

galoisscobi 4y ago
This is an excellent guide. Thank you for taking the time to write it. I wish I had something like this when I started out in tech but helpful people early on taught me about not sending screenshots and sent a link to the XY problem explainer page.
- thundergolfer 4y ago
  Thanks :) I hoped to turn my petty Slack frustrations into a helpful bit of shareable guidance.
TillE 4y ago
The problem with stuff like this (or ESR's How To Ask Questions The Smart Way) is that they only really get through to the people who care enough to want to improve themselves and their interactions, which is probably like 1%. Maybe it's easier if they're employees. But my overwhelming experience out there in the wild is that people ask terrible questions which can't be answered, because they put zero effort into anything.
- thundergolfer 4y ago

madsbuch 4y ago

I have experience that suggests the contrary of his suggestions. Working in a remote culture, often we can spend too much time writing things out and in turn reading things that are irrelevant. I would propose a more progressive framework: Start with the short message without any context. If needed, make a new message with all the context. As an example I have a couple of times asked for help where a response would list the pros and cons of "REST" and I would have to spend too much attention reading it. Alternatively the following would have been perfect: > X is hard to do in Elixir, any ideas? < Defer it to our Next frontend. It is easy to do in JavaScript > Thanks!

onion2k 4y ago
The problem with opening with "> X is hard to do in Elixir, any ideas?" is that it shuts down any conversation about X. You've decided it's hard, but what if you're wrong? What if you could avoid X entirely by doing Y? What if the context around X makes it also hard to do in Next? Adding a little bit of context really helps open conversations.
- Jensson 4y ago
  It is the opposite, being wrong is a really great way to start a conversation, people are really eager to correct mistakes.
  - squeaky-clean 4y ago
    The ol' Barrens Chat Law from WoW. Need to find Mankrik's Wife for that level 20 quest? Don't ask "Where is Mankrik's Wife?" instead say "If anyone is looking for Mankrik's Wife I found her by the auction house in Ratchet" and watch 25 players immediately respond that you're wrong and the real location is X. On a more serious note, while this works it can backfire if someone follows the wrong info too far, and it can make you look clueless if done too much. If you need to do this, I feel the best way is to also phrase it as a question but leading towards the incorrect answer. Something like "I've been trying to get X working in Elixir but keep getting errors. It looks like [library] doesn't support [feature]?"

benjaminmaccini 4y ago

This was a great read and conscious of the nuances to effective writing. Articles like these tend to have a "write this way NOT this other way" mentality. To paraphrase a comment I saw somewhere regarding code optimization: "Given enough time most code can be optimized quite a lot". The same can be said about writing. The audience, the topic, and the intended outcome make for a complex optimization problem that, as the author touches on, can eat up a ton of time. The PR comment example is perfect. The initial comment (on the lefthand side) works. *It does the job*, however when the author is placed in a different context (audience and intent), the comment on the right becomes more optimal. It also took 5x the amount of time to write up. I feel as though knowing the tradeoffs and managing your own time seems to be half the battle when it comes to communicating. My additional advice for devs is; get honest feedback on your writing (slack messages, design documents and everything in between) so that you can learn best what works with whom.

withinboredom 4y ago
I think a lot of this is your “intended audience’s tastes.” I’ve worked with people who will literally write you a book for every reply. The conversation was so incredibly dense you had to spend a long time just to figure out the point if there is even one to begin with.

D13Fd 4y ago

This is a great article with nice examples, and I like the "high resolution" vs. "low resolution" concept. But it leaves off the other side of the equation: know your audience. If your audience wants to read a long, detailed communication, then that's great and you should write a "high resolution" message. If your audience has little time available and no real need to know the details, then the "low resolution" message is much more effective. The real trick is learning how to pack exactly what the reader needs to know into a "low resolution" message.

phinullfermata 4y ago
Someone who doesn't care about the detail can and will stop reading. It's important to get your main point across early because of this fact. The inclusion of detail is helpful but it needs to be in the right place. I think this is why traditional business writing evolved to have an order like summary, recommendation, then supporting evidence. If you've written things well you can get the best of both worlds. I noticed this in the author's review example. The first paragraph gets a reasonably high resolution description of the problem, then the detail follows in the next paragraphs.
- squeaky-clean 4y ago
  Basically the idea of inverted pyramid from journalism. Start with the necessary but minimal amount information up front. Then expand the details in subsequent sentences, the further in you get the more specific and granular you get. If someone feels they've gotten all the information they need they should be able to stop reading at that point.
- D13Fd 4y ago
  I still disagree. Sure, you can get your main point across and then offer extra detail. But the extra detail is often detrimental in that your reader probably isn’t comfortable stopping before they read it. To be clear, I’m talking about business communications here (as was the article), not other kinds of writing. In my field, at least, this is a fundamental concept that differentiates some of the best communicators.

commandlinefan 4y ago

> The examples on the right, on the other hand, try to make the reader do less work, even though it is more effort for the writer Ironically, these are perfect examples of the sort of thing that developers think is better but actually turn out to be worse. I thought the same thing as the author, early on - the more detail I can cram into each message the better. What I've found, though, is that most people actually interpret that as hostility and prefer a short, quick overview followed by more detail when asked.

sokoloff 4y ago
The ones at the top of the blog post? The ones on the right are better for nearly every case I can think of. "what is 'it'?", "who is 'her'?", and "'not working properly' how?" are not the type of detail questions that people generally want to have to ask ever. (maybe the third is sometimes OK)
- commandlinefan 4y ago
  Yep, that's exactly how human communication ought to work, and the world would be infinitely better if it did. But it doesn't, actually.
  - macintux 4y ago
    I have often been frustrated that my attempts to communicate clearly have failed, but I choose to believe that it’s my fault as a writer, not their fault as a reader. The alternative is being a jaded, negative person who is unpleasant to work with. It’s too easy, too lazy, to fall into that trap.
    - travisjungroth 4y ago
      Are you disagreeing with their conclusion or just the vibe? You can do both: believe things would be better with some global change, and also accept that won’t happen and do your best with how things are.
4y ago

451mov 4y ago

> Communicating effectively as an engineer means empathically increasing the resolution of your writing. What does that even mean?...

lordswork 4y ago
To communicate technical concepts effectively, think harder about what may be unclear or misunderstood by the recipient(s) and take the time to address those ambiguities preemptively.

kayodelycaon 4y ago

One of the issues with the effective communication listed is it takes a lot more effort. It can take me up to an hour to get all of my thoughts into words organized for easy understanding. But I'm usually dealing with things much more complicated and detailed that a REST api.

BurningFrog 4y ago

> Writing messages on Slack isn’t what engineers get paid for This is wrong. If you disagree, stop writing messages, and see how long you keep getting paid.

jmartrican 4y ago

The image on this article looks amazing. And it was AI generated. I would not mind seeing art like that in my living room.

BurningFrog 4y ago

Here is my competing take: The biggest problem I see in developer communication is what I call the "assumed context" problem. As in, you talk/write to people as if they know all about your code, except the detail being discussed. In reality, they usually have much less detailed understanding, and you're making no sense to them. I'm pretty sure this is related to people "on the spectrum" often having low "theory of mind" capabilities. People without that will just assume people know what they know, and proceed to fail at communicating with those who don't. It also makes it easy to think of those who don't know what is obvious to you as idiots. The workaround, if you want to communicate with the idiots surrounding you, is to start conversations by fact finding. The question "so how much do you know about the flurbigator system?" can help.

DannyBee 4y ago
I generally agree with this - the first part of any effective communication is to see where you and the other person/people are starting from. Only then can you decide how to try to communicate the rest.
peteradio 4y ago
Alternatively, why is someone who doesn't know the product directing its design without asking appropriate questions on their end?
deleted 4y ago
[deleted]
taude 4y ago
I think you're "assumed context" problem actually has another term called "Curse of Knowledge" [1] (which I believe it's much more known as). There's a ton of strategies that have been written about it. Just adding this term here for people who want to search for strategies on how to work around this. It comes into play in all forms of communication, written, verbal, Slack, etc... [1] https://en.wikipedia.org/wiki/Curse_of_knowledge https://en.wikipedia.org/wiki/Curse_of_knowledge
- 4y ago

strunz 4y ago

Step 1: Don't use a gigantic header and cover image which takes no less than 3 full scrolls of a mousewheel to get to the content.

SevenNation 4y ago

> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Instant messaging tools are seen more as a necessary evil to get work done in a team than anything else. Because of this dynamic, there is a tendency to elide details or cut messages short, sometimes at the expense of legibility. The article is long on tips for individual media without explaining why you'd use one over the other. Digital communication encompasses a wide spectrum of media, each with its best use: - realtime/recorded text (Slack, GitHub issue, README, Comment, etc.); - recorded graphics/text (PowerPoint) - realtime/recorded voice (voicemail, phone); - realtime/recorded video (Zoom, YouTube). The most important question before you use any one of them is: why this medium and not one of the others? Even the right message created well will flop if sent across the wrong medium.

kapitanjakc 4y ago

In my own brain I've created 3 different categories :- Others, Developers, Management. I find it easier to explain stuff to other people by giving context from their field For example to someone in food industry I'd say, frontend is like how you present your food at the table and back-end is like the kitchen where food is prepared. To people in development what I've learnt is that you've got to find the right balance, can't dumb it down a lot or can't switch it up, always in the middle. Management will understand 3 things : Excel, PowerPoint, Money. That takes care of 90% of my conversation.

booleandilemma 4y ago
What makes you think you know anything about the food industry, or the context where people are coming from, in general?
- kapitanjakc 4y ago
  In general I don't, but usually when meeting someone new we introduce each other right? Otherwise if the person is someone you know already there's a better chance that you know what is their line of work. Also It's more of a analogy thing Explain stuff to them in their language. But while writing stuff we don't know who's going to read it, so a general analogy, a bit tech stuff and few visual stuff all of these can be used.

decaffjoe 4y ago

Always worth it to spend 2-3x the time authoring a message with explicit context since it's going to save every reader 2-3x the time figuring out what you're talking about.

chiefalchemist 4y ago

> It's not about you, though.. It's about them. Ironically (given the context), he buried the lede. That aside, if you're interested in raising your comms flag, I recently finished "Smart Brevity". As a solution, it's not a panacea for all use cases. Still, it's a quick and useful read. Simple but effective. https://www.thriftbooks.com/w/smart-brevity-write-less-say-more-get-heard/34185851/?resultid=d22fe885-bd5e-4105-b5df-74b939a79620#edition=61265924&idiq=52276022 https://www.thriftbooks.com/w/smart-brevity-write-less-say-m... I'd also recommend "Words That Work" by Frank Luntz. Chapter 1 is all you need. The rest is simply the lessons from Chapter 1 in practice. https://www.thriftbooks.com/w/words-that-work-its-not-what-you-say-its-what-people-hear_frank-luntz/251558/?resultid=2805995f-7cd0-4c38-a44b-6f93da6b42a9#edition=4919560&idiq=3895357 https://www.thriftbooks.com/w/words-that-work-its-not-what-y...

azangru 4y ago

My biggest communication problem as a developer at the moment is with the designer. It is as if we were speaking different languages — and I am not just talking about the jargon such as "persistent storage" or "api" on one side vs "kerning, tracking & leading" on the other side. No, it's the fundamentally different ways of thinking, and inability to pick up on what's obvious for the other side (as a developer, I, naturally, blame the designer for all these difficulties in communication; but I am sure that she blames me). I am both amused and annoyed at this; not sure which more.

zackmorris 4y ago

I tend to write diatribes that nobody will ever read, so I've switched to writing a quip first, with details below in inverted pyramid style so that the reader doesn't have to ask for more information. --- I usually start with a: # Solution: With links to any tickets/jobs/etc. For example, the inverted pyramid puts the most important info first: https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) Then I'll put any relevant notes and commands that I refer to as: # Discovery: ``` # in a big block of literate programming (Mac only, try `curl -ks` to skip SSL checks if the clock's wrong in your shell) curl -s https://en.wikipedia.org/wiki/Literate_programming | textutil -convert txt -stdin -stdout ``` So that people in a hurry can skip the parts they don't need. Edit: I edited this a lot, might need to refresh

booleandilemma 4y ago
This is how newspaper articles are written. Critical details up front followed by the extra info at the bottom.

jlos 4y ago

It is just as difficult to learn how communicate technical material to peers and lay audiences as it is to learn the technical material itself. Before becoming a dev I spent almost a decade training and involved in Christian ministry, a surprisingly technical field. It's hammered into your head you need to balance technical excellence and impactful communication to lay-audiences. You can't sacrifice either. I don't think devs are given that perspective. Some observations I've had - 'Dev in a cave' do exist though, are more prevalent in software/engineering that elsewhere. They aren't the majority, but you will interact with them if you interact with developers/engineers. - Computer science and engineerings curriculums absolutely do not prioritize good communication. Even if devs come from informal backgrounds, they are in the same boat of needing to learn how to communicate technical material. - Even if most devs understand communication is important, they don't seem to appreciate how much work it takes, and are not likely aware of the ways to develop those skills. - The only real exceptions I've found to the above are people like myself who've come into development from some humanities discipline (philosophy, history, english, etc). Greek, Hebrew, Latin, and maybe a bit of German is the baseline for a theologian worth their salt. Include with that a working knowledge of history (Greco-Roman, Ancient Near Eastern, Mediaval, Reformation/Renaissance era, and Modern), philsophy, linguistics, and literature. These are of course extras on top of the primary area of study in biblical studies, systematic theology, pastoral theology, and historical theology.

jonnycomputer 4y ago

I'm not sure their example of "improved" short-form messaging improves things much. In some ways its worse. We're all being overwhelmed with information, and often the thing we want to know is: is this relevant to me, and what is the gist. The terser the better. For what it's worth, I sometimes go with something like: Update on foobar.py bug: - Script was not updating last-name column in person table - Notified Sarah, and Sarah will push fix soon Details: Blah blah blah, if you aren't interested in all these details, don't read this. But super useful if you need it.

Brystephor 4y ago
> I'm not sure their example of "improved" short-form messaging improves things much The bad short form message is bad because 1) it's ambiguous and 2) it has a short lifespan. By lifespan, I mean the time that a message can be read and can be useful. Using terms such as "it" and "she" leave a lot of ambiguity. If you read the message 7 days later, 1 day later, maybe even an hour later, all context of what "it" is and who "her" is could be lost. Using names instead of "it"/"her" means you can read the message 24 hours later, maybe even a week later and still understand what it was, or at least it gives you more information to figure out what the context was. In short: I think the improved message is significantly better than the first. > The terser the better. In general I agree with this. I have no evidence but I'd bet some people prefer the conversational message over the status update. Again, it depends on the context. If it's a status update, make it a status update. If it's a conversation, let it be one.

witnesser2 4y ago

I think some epic SE failures, the DOJ LE should get involved. So the engineers' habit of providing details in written materials is indisputable potential forensic self defense. Like the egg Greg in succession, he has a filmsy shell, but it protects, serves when needed. My first civil engineering trainings, our department head she repeatedly stated and gave examples that 'you may go to jail if you don't follow the design rules and it failed' like this. There is nothing called communication in engineer's world. That means plane fell, bridge collapse -- they are negotiable. This is a community talk of opinions.

canadianwriter 4y ago
...does this make sense. These seem like words that should go together but I can't grok what is being said.

squeaky-clean 4y ago

This comment only applies to bug report / support request issues, but my personal rules that seem to work well are: What happened? What did I expect to happen? What actions did I do to make it happen, or if it's an automated task then mention that. Then list any errors/logs/etc I've already found that I think are directly relevant. Then what I've already tried to fix it (if applicable). Then what I think should be tried. Then any additional logs/errors/etc that I'm not sure are relevant, but also that I'm not sure are irrelevant. So something like "Hey I'm trying to deploy X but getting a ModuleNotFoundError for Y in the Jenkins build step. It builds successfully on my local machine. I'm running make deploy-dev and getting the error. Running make deploy-local gives no error. This is the error [codeblock quote of the relevant error line]. Here is a link to the Jenkins output for my most recent build [link] I've added the module to setup.py and I see Jenkins says that it installed the module [quote of Jenkins output line]. Maybe clearing the Jenkins cache would help? This is probably not related but I see Jenkins also logged a JVM Heap Memory warning at the start of the run."

itsmemattchung 4y ago

I'd argue that the most important thing to consider when trying to communicate effectively is this: know your audience. One "low resolution" (using author's terminology) sentence might actually communicate more effectively than a "high resolution" one, given the right context and right audience. Similarly, a "high resolution" text over explain and perhaps even offend the reader. In short, it depends.

jb3689 4y ago

Writing too much is just as bad as writing too little. It really depends on context. If I write you an essay and the salient points are buried, that’s even worse than being short and lacking clarity. At least in the latter case the receiver can ask for clarification

dannas 4y ago

=== Cut needless words === The article references Covingtons How to Write more Clearly, Think More Clearly [...] Powerpoint presentation [1]. I highly recommend it! A fun part in that presentation is when Covington, in a series of steps, revises this sentence... “One of the best things you can do for yourself to improve your writing is to learn how to cut out words that are not necessary.” ..Into this one: “To improve your writing, cut out unnecessary words.” OPs article calls for more words to provide context. But by revising you can often cut the length in half. [1] https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf

AtNightWeCode 4y ago

Agree with most of it. But I think the response to the PR was unnecessary. I would have pointed out that it does not work and told the person to remove it or fix it.

kebman 4y ago

Here I am, the copywriter slash programmer slash musician. Yes, I play the keyboard.

oxff 4y ago

Learn to adjust your abstraction and resolution to the intended target audience. That's about it.

rib3ye 4y ago

In short, part of your job is spending 3-4x more time thinking about how to write for the human psychology computer.

tristor 4y ago

As someone who went from engineering to product management, partly due to having developed a skill of communicating effectively in writing and in speech, I would suggest perhaps the most important part of communicating effectively is storytelling. If what you are sharing does not have a clear and obvious narrative arc, people are going to disengage quickly. This is not necessary for short bursts of information in a high-context environment, but any time you need to level set and share context before communicating the critical information, you should do so in story fashion. If you want to level up your technical communication, I'd highly recommend taking classes in creative writing, participating in things like NaNoWriMo, or taking a class in improv comedy/theater. All of these things emphasize construction of narrative arcs and how to draw people through a story, which are essential communication skills. This gets more important the farther up the chain of command in a company you are communicating with.

wcedmisten 4y ago
I recently watched Kelsey Hightower's Strange Loop talk on "The Secure Software Supply Chain", which incorporates a humorous narrative about deploying code found on a flash drive in a coffee shop. I think the talk was especially captivating because of that. I'm trying to incorporate that narrative aspect into my own demos and presentations now. https://m.youtube.com/watch?v=JC-xCXcyNXI https://m.youtube.com/watch?v=JC-xCXcyNXI
zwkrt 4y ago
Completely agree, although I don't think that people need to be better creative writers to be better at creating narrative arcs. For work, your narrative arc is normally solved if you are understanding (1) the relationship between you and your audience, (2) what you want, and (3) why your audience should care. If you communicate those things, the narrative should be crystal clear. That depends heavily on the context. "Hi, I'm from a team from far away in company land (1). I've been having an issue with your service for the last few weeks because it seemingly drops connections sometimes. I looked at your metrics and I see that this is happening to other clients as well. This issue is stopping us from deploying a change to the UI that we promised customers would go out next week (2). Can you help me debug from your side? (3)" "Hey boss (1). I think that I need more support on this project (2a). We originally thought it would be easy to refactor a widget into a widgetFactory, but after I investigated it widgetFactories will require a schema migration (3). I think Sarah is really good with those, can I ask her to work on this with me (2b)? "Apache upgrade production outage thread (123)"

karmelapple 4y ago

> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Perhaps I'm being picky, but... that's also not what engineers get paid for, either. I think engineers get paid to do things that solve problems. Sometimes that involves writing code, but sometimes it absolutely involves writing a Slack message, having a call, or just thinking a little more. A Slack message might be, "Got a minute to chat?" to start a voice call that will clarify some requirement that's been bogged down in a quagmire of too much writing or conflicting ideas. Requirements are clarified, maybe not a single line of code is needed to be written, thanks to a better understanding of the customer's desires. A Slack message might ask, "Does this change work instead?" with an image attached of a simpler approach. I wouldn't typically respond to one line from a blog post, but since this was up so high in the post, I felt I needed to gently encourage a little rewrite of this sentence :)

deleted 4y ago
[deleted]
deleted 4y ago
[deleted]

mcculley 4y ago

These points are generally true to anyone who ever has to write an email or text message as part of a job. This could be generalized to "How to communicate effectively as a knowledge worker".

raydiatian 4y ago

> empathically increasing the resolution of your writing I find this to be obnoxious and nonsensical, which, in an article about communicating effectively, is ironic.

datavirtue 4y ago

This reads like a bullet list of things you should have picked up in the five-to-ten English/writing classes you took in high-school and college.

analog31 4y ago

>>>> Writing effectively is a superpower, there is no denying it. As a software engineer, you write a lot. Most of the writing you do is for computers. Businesses, however, consist of people. Someone wrote that code is meant to be read by people, and secondly, by the computer. Lack of writing skill could spell trouble for the quality of the code, should anybody need to read it, days or months later.

stack_framer 4y ago

I think we overlook wordiness too often! In fact, each "good" example in TFA can be shortened without losing context: Good: "I checked the foobar.py script and told Sarah that there was a bug related to updating the users table in SQL — the script does not seem to update the last name column." Better: "I found a bug in foobar.py and told Sarah it's not updating the last name column in the users table." Good: "Hi team, the email sending worker keeps crashing with the following exception. I've tried re-running, clearing the cache, re-installing dependencies. Can I get a hand?" Better: "The email sending worker keeps crashing with the exception below. I reran it, cleared the cache, and reinstalled dependencies. Can I get a hand?" Good: "The resource defines two routes, but the GET handler can only handle one of those — the one without any path params. I can technically make a request GET /api/foobar/123/456 and have the app crash with a 500 because there is a route but the handler doesn't take any params. Roughly speaking, there are two "types" of resource endpoints — list and singular. List type resource endpoints handle - getting a list of resources: GET /things - creating a new resource: POST /things Singular type resource endpoints handle - getting a single resource: GET /things/123 - updating a single resource: PATCH /things/123 - deleting a single resource: DELETE /things/123 To handle all cases properly, you need two resources: ... " Better: "The resource defines two routes but the GET handler can't take path params, so a request to GET /api/foobar/123/456 crashes the app with a 500. There are two "types" of resource endpoints: List: - get a list of resources: GET /things - create a resource: POST /things Singular: - get one resource: GET /things/123 - update one resource: PATCH /things/123 - delete one resource: DELETE /things/123 So you need two resources: ... "

pnt12 4y ago
You can have both of best worlds using BLUF: bottom line up front. I didn't read the code because it's too early to debug someone else's code, but here's an example: These endpoints break REST conventions and will be harder to understand and maintain. The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>. I find it useful for two reasons: - maybe you parse the first paragraph and you have enough context to act, so you skip the second - or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details

maxrev17 4y ago

People who understand the problems tend to be disinterested in those being paid to 'manage' them. I think that's the foundation for most of the issues.

SinParadise 4y ago

The first order positive and second order negative speaks to me. I prioritize the former over latter unless I am creating a demo/presentation of some kind. I still see defaulting to prioritizing second order effect as a waste of effort majority of the time.

aymar_99 4y ago

One thing i can share from my experience is, some people communicate poorly because of laziness. In this case, Even if the vague communication is understandable to you since you are aware of the dev's current WIP, pretend you don't understand and nudge the developmer to add more details for the context as necessary. For example let's say your team has 5 services. The developer pings you : when starting the service i am facing this exception, tried different ways couldn't figure out, can you please help? . Questions : Which service is he trying to start? Which machine is he trying to start?(local/virtual). He probably doesn't mention these details because he thinks you must be aware of what he is working on. Even if you know the same, you can ask these questions and ask to mention such infos going forward to improve their communication. The idea is to communicate clearly as with any developer and not to take things for granted due to laziness in typing the relevant details.

deleted 4y ago

[deleted]