[HN Gopher] How to communicate effectively as a developer
___________________________________________________________________
How to communicate effectively as a developer
Author : karls
Score : 367 points
Date : 2022-10-28 13:04 UTC (9 hours ago)
(HTM) web link (www.karlsutt.com)
(TXT) w3m dump (www.karlsutt.com)
| analog31 wrote:
| >>>> 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.
| oxff wrote:
| Learn to adjust your abstraction and resolution to the intended
| target audience. That's about it.
| SevenNation wrote:
| > 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.
| nipponese wrote:
| In short, part of your job is spending 3-4x more time thinking
| about how to write for the human psychology computer.
| jlos wrote:
| 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.
| karmelapple wrote:
| > 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 :)
| magicalhippo wrote:
| 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.
| kayodelycaon wrote:
| 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.
| smileysteve wrote:
| 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 wrote:
| > 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?
| luckylion wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| BurningFrog wrote:
| > _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.
| itsmemattchung wrote:
| 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.
| madsbuch wrote:
| 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!
| commandlinefan wrote:
| > I have experience that suggests the contrary of his
| suggestions
|
| Yep, this is the "internet blog" phenomenon. The author
| asserts, without any evidence, that _X_ ought to be true,
| therefore _X_ is true.
| madsbuch wrote:
| On the contrary I think treating DMs in an internal chat tool
| as blogging is quite harmful.
|
| As elaborated in another comment, I do trust my peers to
| point out errors in my assumptions.
| onion2k wrote:
| 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 wrote:
| It is the opposite, being wrong is a really great way to
| start a conversation, people are really eager to correct
| mistakes.
| squeaky-clean wrote:
| 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]?"
| madsbuch wrote:
| Two people pointed this out with this commentary.
|
| This is the exact point. I trust my colleagues in asking the
| right questions. _Unless_ I shut them down with a wall of
| chatter.
|
| > X is hard to do in Elixir, any ideas?
|
| < We don't really need X for now
|
| > Thanks!
| [deleted]
| bsenftner wrote:
| This is one of the more critical issues of our industry, of our
| entire society actually.
| jonnycomputer wrote:
| 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 wrote:
| > 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.
| kapitanjakc wrote:
| 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 wrote:
| What makes you think you know anything about the food industry,
| or the context where people are coming from, in general?
| BurningFrog wrote:
| 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.
| bitwize wrote:
| I have a tendency to info-dump to establish shared context, and
| people find _that_ insulting as well. So it can turn into a
| dilemma of:
|
| Info-dump: "I know that already! What do you think I am, an
| idiot?"
|
| Assume context: "In English, please! I didn't get my MBA to be
| made to look like an idiot."
|
| Excuse me for failing to read your mind and know exactly what
| you know and what you don't before I begin.
|
| Those of us on the spectrum are set up to fail by NT-centric
| culture. You think _we 're_ mind-blind? It goes both ways, look
| up "double empathy problem". It's just that most people are NT,
| so by default _we_ have to accommodate _your_ neural quirks but
| the vice is not versa.
| aeze wrote:
| I think there are ways to learn how much context the other
| party needs - like asking them in the beginning of the
| conversation.
| pickledish wrote:
| When you say "NT-centric culture" I think you're talking
| about this, right?
|
| https://www.myersbriggs.org/my-mbti-personality-
| type/underst...
| yberreby wrote:
| I assume it means "neurotypical" here.
| cratermoon wrote:
| I work with a developer* who draws labelled boxes and arrows
| for diagrams and posts screenshots of code in response to
| questions I put to him. I can't say I've been able to find more
| than a handful of places where he's put words together into
| sentences and paragraphs. Getting useful information out of him
| is like pulling teeth. Even when he _could_ link to code on the
| git server, e.g., he doesn 't.
|
| His screenshots are the worst-case scenario of lack of context
| - just a couple of dozen lines of code, no information about
| where, in what file, in which repo, he's given.
|
| * We both work remotely and live in different states, nowhere
| near each other.
| nuancebydefault wrote:
| Ivwould feel a bit offended if somebody would send me
| screenshots withoutva word of context. Often times the
| explanation of the context is a big part of a solution to a
| problem, or even shows the problem to be non existing.
| cratermoon wrote:
| I've only been working with the person about 6 weeks. I
| didn't think too much about it at first, though it did seem
| odd and unhelpful. It's only in the past couple of weeks
| that I've started to find it irritating, and yes,
| offensive. I will probably bring it up to the lead at some
| point.
|
| By the way, I double-checked my assertion that he doesn't
| use words, in case there were some documents I forgot or
| had missed. Nope. At best, his diagrams or screenshots will
| have captions. Those captions remind me of the sort of
| useless comments we've all become conditioned to ignore.
| x = y + z; // set x to the sum of y and z
| peteradio wrote:
| Alternatively, why is someone who doesn't know the product
| directing its design without asking appropriate questions on
| their end?
| P5fRxh5kUvp2th wrote:
| I just got out of a conversation where surprise was expressed
| that I didn't know, and prepare, for an upcoming release that
| was obviously coming.
|
| Well the answer is that no one told me that they were even
| thinking about releasing. The last I heard we were waiting on
| the vendor.
|
| Apparently I should have known it was coming and had prepared
| production servers for it so the roughly week and a half given
| magically became enough.
|
| What's worse is that technically speaking it can be easily done
| in that time, it's a people problem. They could technically put
| pressure where it needs to be, but will they? All signs point
| to no.
|
| ---
|
| So while I understand putting responsibility for communication
| onto the developer, there's a responsibility for the others as
| well and at some point it's just flat not the developers
| problem.
| bragh wrote:
| I generally agree with your post, but that question is really
| bad, as it can be seen as mansplaining. The fact finding is
| fine, but requires a gentler approach.
| roenxi wrote:
| > I'm pretty sure this is related to people "on the spectrum"
| often having low "theory of mind" capabilities.
|
| As an alternate theory, maybe they've spent a lot of time
| staring at the code in question and internalised the context to
| a point where they no longer think about it. Happens to
| everyone.
| _greim_ wrote:
| > The biggest problem I see in developer communication is what
| I call the "assumed context" problem.
|
| Ah yes, the "shouting up from the rabbit-hole problem".
|
| > people "on the spectrum" often having low "theory of mind"
| capabilities.
|
| I somewhat take issue with this, as people on the spectrum are
| more likely to over-communicate, all other things being equal.
| Techies are rather caught in a web of social status pressures.
| Draw a 2x2 grid. On the top axis is the correctness versus
| incorrectness of your assumption. On the side axis is whether
| you assume ignorance or knowledge. The social calculus always
| favors assuming a prior understanding:
| correct incorrect
| +--------------+--------------+ |
| | | | |
| lose | ignorance | neutral | status
| | | | points |
| | | |
| +--------------+--------------+ |
| | | | |
| | understanding | points | points |
| | gained | gained | |
| | | | |
| | +--------------+--------------+
| kodah wrote:
| I agree, it's really not worth exposing yourself to the risk.
| Ignorance-Correct can even be interpreted as a micro
| aggression.
| A4ET8a8uTh0 wrote:
| <<I somewhat take issue with this, as people on the spectrum
| are more likely to over-communicate, all other things being
| equal.
|
| I don't think I am on the spectrum ( I mean, I guess
| technically everyone is, which is why its a spectrum ), but I
| do know that I was ..what is a good word.. chastised.. no..
| maybe gently admonished for putting up very long detailed
| summaries with some discussion of potential risks involved in
| an assumed approach, potential tradeoffs and pitfalls.
|
| It really depends on your boss, but I come from compliance
| world, where you do want to CYA pretty extensively.
|
| Anyway, back to the story. I was effectively asked to keep
| writing executive summaries. I hate to say it, but things
| seldom are that simple. I can simplify it for you, but you
| will lose a lot of context with that. And this how we get to
| the situation, where only one guy in the entire company knows
| how X actually works with all the constraints that it brings.
| cjblomqvist wrote:
| I agree (I think). I think the point is that by talking
| about the details the receiver doesn't get it more - it's
| more that some details stick instead (and thus the big
| picture is lost).
|
| Thus, the only way forward is to summerize, and then point
| out that there are details/nuances (but not getting into
| it). Only if the there's interest in those nuances, then
| it's relevant going into them.
|
| Same as with physics. First you learn Newton. Then you
| eventually realize Einstein adds nuance to the formula.
| Start with Einstein and it becomes much more complex, hard
| to grasp and less likely you'll understand anything. And,
| equally important. If the receiver doesn't want to know
| Einstein, then no point in talking about him.
|
| One big problem I see nowadays is that more people do not
| care about the details, meaning it's less useful as a
| communicator to communicate then - but also that people do
| not fully grasp as much the nuances and believe (and search
| for) simple answers - and come to dangerous conclusions
| about them. From my POV this is the danger with the
| attention economy, leading to Trumpism and similar
| phenomena.
| galaxyLogic wrote:
| Right it's as if the low-information people are saying
| (and believing) "I have just as much the right to be
| correct as anybody else. It's my right. Don't tell me I'm
| wrong because it is my right to be the one who tells what
| is the truth".
| nescioquid wrote:
| > One big problem I see nowadays is that more people do
| not care about the details...
|
| I think people today care about the details just as much
| as people used to. It's just that there are so many more
| details to care about today.
|
| The exhaustive CYA-flagging of risks (and similar
| behaviors) denotes more a problem of how incentive are
| aligned in that workplace rather than any lack of skill
| with words.
| cjblomqvist wrote:
| CYA?
| _greim_ wrote:
| Cover your ass.
| californical wrote:
| I think your chart is incomplete, because in the bottom-right
| quadrant, there's the caveat that they never ask for
| clarification and blindly do the wrong thing.
|
| Then when you have to go back and tell them the basic
| assumptions that they are wrong about, and that they have to
| redo tons of work, you lose a giant sum of hypothetical
| points
| _greim_ wrote:
| My theory is that devs often trade pretense-now for
| research-later. This habit allows them to gain ~0.002
| status points here and there. But now combine that with
| unknown-unknowns. The thing they're hearing--if they
| actually understood it--ought to cause them to abandon or
| completely rethink a change they're currently working on.
| But because their takeaway isn't new knowledge, but a
| placeholder for potential new knowledge, they end up losing
| 15 status points when it blows up, in a way that was
| utterly unforeseeable.
| dllthomas wrote:
| IME, this is exactly the difficulty that "ELI5" addresses. By
| asking people to dramatically underestimate understanding,
| they are comfortable undershooting without implying
| disrespect.
| jonahx wrote:
| Bottom right should be "points lost" imo. For me, the most
| points lost, as there is nothing more annoying than someone
| assuming context I don't have.
|
| It seems that this chart assumes:
|
| 1. Everyone is a baby that gets their feelings hurt when you
| imply they might not know something they do in fact know (top
| right).
|
| 2. Everyone loves being alpha nerd and making people feel
| dumb for not knowing things they know (bottom right)
|
| While both of those are real phenomena, they are pretty
| dysfunctional. Many people (most people?) enjoy genuine
| cooperation within a context of mutual trust, learning things
| from others, and teaching others who want to learn. In that
| context, checking for knowledge is not a slight, and assuming
| things "are obvious" and failing to explain them is not a
| flex.
| _greim_ wrote:
| Yes, I'm for sure describing a perverse incentive
| structure, but one that's easy to fall into, almost a
| default state. If you get enough well-intentioned people
| together they can break the cycle, and then you have a
| healthy team.
|
| > Bottom right should be "points lost" imo.
|
| There's a certain breed of hot-shot dev who truly believes
| they're gaining status by making cryptic, in-the-know
| references, and there's another breed who falls for it.
| When it comes to social status games, if enough people
| believe it, it becomes true.
| johnchristopher wrote:
| > > people "on the spectrum" often having low "theory of
| mind" capabilities.
|
| > I somewhat take issue with this, as people on the spectrum
| are more likely to over-communicate,
|
| Low theory of mind is definitely not incompatible with over-
| communication.
| Jarwain wrote:
| If anything over-communication sounds like a coping
| mechanism!
| _greim_ wrote:
| It's definitely a coping mechanism. When you've been
| burned repeatedly by people nodding vigorously in
| understanding, then turning around and revealing a
| complete lack of comprehension, forcing you to either
| intervene or allow the error to propagate, it's tempting
| to fall into a habit of pre-emptively explaining
| everything.
| johnchristopher wrote:
| > revealing a complete lack of comprehension, forcing you
| to either intervene or allow the error to propagate, it's
| tempting to fall into a habit of pre-emptively explaining
| everything.
|
| Or maybe the explanation was bad to begin with. Over
| communicating won't turn a bad explanation into a good
| one. Understanding something doesn't mean you know how to
| explain it to someone else.
| [deleted]
| _greim_ wrote:
| > Understanding something doesn't mean you know how to
| explain it to someone else.
|
| Too true. Explaining things is hard. My gripe is mainly
| people's tendency to pretend they understand in
| perpetuity, instead of expressing a modicum of curiosity
| about it. "What does 'TPS' stand for actually?" As
| mentioned, explaining things is hard, and I think I'm not
| alone in needing help identifying gaps in my
| explanations.
|
| That said, I also understand that there are huge social
| barriers to admitting a lack of understanding in the tech
| industry, especially for juniors.
| nuclearnice1 wrote:
| I like your opening question. A casual way to establish some
| context and rapport.
|
| I'm not sure this is a competing take vs the article. More like
| complementary.
|
| The article mainly says "add more details." Eg. Don't write
| "the system is broken" be specific about what's broken, what
| you did, and if you need help.
|
| Basically, don't assume context.
|
| The author takes himself to be some kind of writer, so he said
| it in too many words.
| [deleted]
| DannyBee wrote:
| 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.
| kitanata wrote:
| I am a Staff Engineer leading a large engineering organization.
| I am also "on the spectrum" and openly autistic. My co-workers
| know that I am autistic.
|
| I have found that communicating to business folks and leaders
| is a skill like anything else and can be taught. Your
| assumption that being autistic somehow completely disqualifies
| one to speak competently to others is ableist and harmful.
|
| While it is true that people who are autistic struggle to
| communicate with non-autistic people I would argue it is also
| difficult for non-autistic people to communicate with autistic
| people.
|
| It is also ableist to assume that just because someone lacks
| communication skills that they are "on the spectrum".
|
| What is true is that communication as a skill is not often
| taught to developers.
| taude wrote:
| 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
| ladyattis wrote:
| This is something I wrestle with at work all the time. I try
| to break things down to make them comprehensible but I wind
| up forgetting to frame the discussion to give the context
| needed to get input even from fellow developers.
| thundergolfer wrote:
| _Curse of knowledge_ is a different thing. The "assumed
| context" problem isn't a teacher-pupil or expert-novice
| dynamic. It's just someone not providing enough context to an
| audience that would otherwise be able to understand and help
| them.
| Consultant32452 wrote:
| I can speak to what it's like with autism brain.
|
| In conversations people often say things that I have unusual
| associations about. My mind will start spiraling about the
| unusual association and I will begin an internal narrative
| about the new, unrelated topic without verbalizing any of it.
| I will continue with the original conversation with the convo
| partner. Then, out of the blue, I will verbalize something
| about the second topic and the convo partner has no idea what
| I'm talking about. The topics can be as unrelated as
| databases and the mating habits of penguins. I have forgotten
| that the convo partner did not take the journey into the
| second narrative with me.
|
| Countdown to database of mating habits of penguins comment.
| MonkeyClub wrote:
| > Countdown to database of mating habits of penguins
| comment.
|
| 19 minutes.
| cjblomqvist wrote:
| That's very clearly stated - I recognize it so much from my
| son (who has autism)! Thanks for putting it out there!
| roflyear wrote:
| Alternatively, people who have to explain everything problem
| from the creation of the universe are even worse. They waste
| everyone's time and come across like they think you're an
| idiot. There is a middle ground, but I much prefer if you are
| direct and get to the point and allow me to ask questions over
| the alternative where you spend a lifetime bc you're not sure
| what I know already.
| chiefalchemist wrote:
| > The biggest problem I see in developer communication is what
| I call the "assumed context" problem.
|
| Yes, that's often it. But it's also not exclusive to devs. As
| the receiver I've learned to say / ask, "I don't follow. Can
| you clarify?"
| frodetb wrote:
| I think this is a big one as well, and would go one step
| further and say that anyone no matter their place on the
| spectrum may fail at communication in this way. I bet most
| junior developers know what I mean, if they've sat in meetings
| with senior guys talking about something esoteric.
|
| One simple trick, I think, is to avoid extensive use of
| pronouns. A sentence like "Because of that, it doesn't find it
| there" might be clear enough when you know the context, but is
| meaningless if you don't. Filling in "that", "it", "it", and
| "there" would help tremendously. It will make sentences awkward
| if you avoid them completely, of course, but I think sentences
| that contain nothing but pronouns are a red flag.
| JadeNB wrote:
| As a math teacher, I try to instill a similar idea in my
| students, and am glad to hear that the idea is useful in a
| broader range of situations!
|
| In overstated form, my version of the idea is: "never use
| 'it'"--because a student just learning mathematical language
| will have many different 'it's in mind, or, even worse, _no_
| clear idea of what 'it' is. (For example, I 'll often see an
| application of the derivative summarized as "since it is
| negative, it is decreasing", which is correct only if you
| change 'it's midstream--but students often don't realize that
| they are, or should be, doing so.)
| mjw1007 wrote:
| The idea that programmers have a poor theory of mind doesn't
| stand up at all in my experience.
|
| I remember once seeing the inbox of someone working as a sales-
| ledger clerk. It was full of messages with the subject
| "accounts query", or a small variation of that. The ones with
| subjects like "query for account ACME-37" were from technical
| staff.
|
| Similarly if I ask "when do you need those figures?" and I get
| the answer "next Wednesday", it isn't when I'm talking to
| programmers that I feel the need to follow up with "Is that
| when you want me to give them to you, or when you're going to
| be making the presentation that includes them?".
| slillibri wrote:
| I suppose, but as someone in infrastructure I have had
| developers ask very, very specific questions without ever
| actually providing the context or what they were actually
| trying to solve. Seems to me to be a variation on the same
| problem. Just because a question is specific doesn't mean
| it's the right question.
| mjw1007 wrote:
| My view is that, whatever is causing developers to often be
| bad at filling in context, it isn't a deficiency in their
| theory of mind.
|
| (Similarly, someone elsethread is talking about how their
| non-developer colleagues neglected to tell them about an
| upcoming release. One possible explanation is that their
| colleagues were bad at "theory of mind", and believed that
| as they knew about the release, so did everybody else. But
| I think it's more likely that they were too disorganised to
| make sure that it was somebody's job to tell everyone who
| needed to know.)
| fsckboy wrote:
| > _The ones with subjects like "query for account ACME-37"
| were from technical staff._
|
| if you get an email from me, and when you want to follow up
| you're thinking "what was that phone number I should call?",
| don't worry, I have already put it in the subject line along
| with the person's name and the deadline
| blowski wrote:
| For any theory about a common pattern of behaviour, there
| will be many exceptions that don't fit the theory. Without
| hard data, both sides are giving a subjective opinion based
| on their experience, and both sides are probably right in
| part.
| ChrisMarshallNY wrote:
| 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/
|
| [1] https://littlegreenviper.com/series/shorties/
|
| [2] https://www.danpink.com/2005/05/mini-sagas-another-approach/
| benjaminmaccini wrote:
| 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 wrote:
| 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.
| mcculley wrote:
| 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".
| dglass wrote:
| 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-...
| kebman wrote:
| Here I am, the copywriter slash programmer slash musician. Yes, I
| play the keyboard.
| jb3689 wrote:
| 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
| massung wrote:
| 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.
| maksimur wrote:
| 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 wrote:
| _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.
| aliqot wrote:
| 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.
| datavirtue wrote:
| 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.
| azangru wrote:
| 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 wrote:
| 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)
|
| 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 wrote:
| This is how newspaper articles are written. Critical details up
| front followed by the extra info at the bottom.
| strunz wrote:
| 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.
| raydiatian wrote:
| > empathically increasing the resolution of your writing
|
| I find this to be obnoxious and nonsensical, which, in an article
| about communicating effectively, is ironic.
| decaffjoe wrote:
| 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.
| witnesser2 wrote:
| 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 wrote:
| ...does this make sense. These seem like words that should go
| together but I can't grok what is being said.
| D13Fd wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| mfuzzey wrote:
| I think it's far better give the reader as much information
| as reasonable and let him decicde how much he wants / needs
| to read. That can avoid multiple round trips and makes sure
| the whole picture is available to anyone who may need it.
|
| Particularly as often the same message will be sent to
| multiple recieients that have different needs.
|
| Of course you should try to structure the message so that
| people don't necessarilly have to read all of it.
|
| For instance I recently sent a message about an analysis of
| the feasibility of changing a piece of hardware to a group
| that contained
|
| * Managers * Hardware developers (in charge of implementing
| the hardware modification) * Software developers (in charge
| of adapting the software to the new hardware)
|
| So it started with a brief summary of the idea and
| conclusion "yes it will work" (for the managers).
|
| Continued with a some comments, questions addressed to the
| hardware team "the aproach is fine but we still need to
| sort out X,Y,Z"
|
| And finished with a detailed description for the software
| team of how we should integrate the new hardware whilst
| remaining compatible with the existing.
| AtNightWeCode wrote:
| 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.
| zerop wrote:
| 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
| chiefalchemist wrote:
| > 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-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-y...
| squeaky-clean wrote:
| 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."
| jmartrican wrote:
| The image on this article looks amazing. And it was AI generated.
| I would not mind seeing art like that in my living room.
| tristor wrote:
| 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 wrote:
| 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
| javier_e06 wrote:
| 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 wrote:
| Add in it's basically impossible to get anyone in the company
| to reply to a comment on a ticket or read an email...
| dannas wrote:
| === 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
| thundergolfer wrote:
| 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....
|
| 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
| fortylove wrote:
| I usually dislike processes like what you describe as they
| normally just add friction, even if there are good parts. But
| as a senior eng, I find your list very good. Thanks for
| sharing!
| TillE wrote:
| 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 wrote:
| I somewhat agree, but where I worked people were motivated to
| improve themselves, and you can't build an effective
| organization assuming your new hires don't care; you at least
| have to try.
|
| (ie. I can't go to my manager only ever with complaints and
| no action)
| galoisscobi wrote:
| 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 wrote:
| Thanks :) I hoped to turn my petty Slack frustrations into a
| helpful bit of shareable guidance.
| commandlinefan wrote:
| > 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_.
| [deleted]
| sokoloff wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| leepowers wrote:
| But ... the examples on the right are short, concise, and
| effectively communicate the problem. The left examples contain
| no actionable information, wasting the time and attention of
| everyone in the channel/thread.
|
| Maybe working in an adversarial or dysfunctional work
| environment is what leads to misinterpreting a detailed message
| as hostile.
|
| Or the team needs to learn to use communication tools
| effectively. Slack messages should be concise. But a bug report
| doesn't always fit neatly into a few lines of text. Use an
| issue tracker for detailed reporting and Slack/email for
| informal conversations.
|
| Either way the point of the blog post stands - everyone needs
| to communicate clearly and avoid ambiguous language. If I send
| an ambiguous message to 10 people, I've just increased their
| mental overhead and frustration, ultimately distracting the
| team and slowing them down. Instead, I should take a moment and
| try to look at it from their point of view and try to
| communicate what they need to _hear_ and not what I want to
| _say_.
| squeaky-clean wrote:
| For taking with non-technical teammates I'd agree, but these
| examples look like developer-to-develeloper or support-to-
| developer, in which case I don't agree. Good communication is
| also about knowing who you're communicating with.
|
| If I get sent any messages like those examples on the left it
| actually upsets me. If someone sends me "the worker is having a
| bad time", first thing I'm doing is taking 10 seconds and
| breathing before I respond. It's just so disrespectful to the
| people you're trying to get to help you. There's also the
| common issue of someone dropping a meaningless "left-side type
| message" and then when you later see it and respond for
| clarification they're in the bathroom or at lunch.
|
| There's a 20% chance I'll respond with something sarcastic
| like:
|
| "Why are you referring to yourself as 'the worker' instead of
| your real name? And why are you having a bad time?"
|
| If I'm in a less sarcastic mood I still have to ask:
|
| "what is the worker? What do you mean by a bad time? What
| environment (local/dev/prod?) How can you tell it's having a
| bad time? What is an example of having a good time?"
|
| If you want to keep the first message as a brief overview,
| that's fine, but you can send a 2nd message with more info, in
| slack you can comment on your own message as a subthread. I
| will say sometimes inexperienced people have the opposite
| problem of a massive info dump it takes you forever to parse
| through. That's not great either. But there is a middle ground.
| AlanSE wrote:
| > If I get sent any messages like those examples on the left
| it actually upsets me.
|
| I spend lots of time responding to issues and informal
| messages like that. Processing vague reports like this is
| nearly a daily task for me. The examples there cut deep for
| me.
|
| Writing well just isn't natural. Mentally, you're on one
| level of the stack, and it takes work to back it out again.
| My forever case-in-point about this is log messages. Log
| messages are, by default, written terribly because the reader
| is not kept in mind. The log will be encountered with little
| context (maybe a timestamp) in the middle of a 5 MB file. If
| you are inside of a nested loop, your message formatting
| _needs to include both loop variables_, and when those are
| objects, there's a very non-obvious decision about what data
| from them is relevant to the log.
|
| It's the same in human communication. Conversations do have
| context, yes. You can and should relax the rules of context
| as you get the ball rolling in a 1-on-1 chat with someone,
| but with many people in a room, or when starting a
| conversation, it's so important.
| squeaky-clean wrote:
| Agreed so much about log messages. I have a personal rule
| about them. You know how when you fix a bug it's good
| practice to add a regression test alongside the bugfix, so
| it's harder to introduce again? My rule for logs is that if
| I had to debug something and the logs did not make the
| problem obvious, change the logs so it will be obvious next
| time. Even with a bugfix and regression test, there will be
| similar bugs it will help catch. Or at the very least help
| you quickly prove that a new issue you're seeing is not a
| regression of that past bug.
| thundergolfer wrote:
| You can send them https://thundergolfer.com/communication/sla
| ck/2021/02/24/how....
|
| I used to get a "the worker is having a bad time" daily, but
| my other main pet peeve was screenshotting error messages and
| stacktraces.
| squeaky-clean wrote:
| I've tried something like that once (not that exact link)
| and it came off as hostile. Maybe there's an appropriate
| time to send it to others, but I believe it's the kind of
| article you need to find under your own motivation.
|
| The best method I've found (though there's probably a
| better one) is to just suggest one or two of those
| checklist items during that conversation.
|
| It's Friday morning and this is HN, not slack/email so my
| comment had a little extra snark. But in reality my full
| message would probably be like
|
| "Why are you referring to yourself as 'the worker' instead
| of your real name? And why are you having a bad time?
|
| Just joking of course ;) but can you please include some
| details about which worker you mean? Is something not
| happening that should be happening? Or is something
| happening too frequently? Is this in production or on your
| local machine?"
|
| > my other main pet peeve was screenshotting error messages
| and stacktraces.
|
| The absolute worst I've ever gotten was a screenshot of a
| database tool with a long-ass query and the output table
| where the only identifying columns are 24 character long
| objectIDs which are truncated because the columns are too
| narrow. With the message "the data for these locations is
| incorrect".
|
| That was when I was at a travel-focused company and was the
| main maintainer of our locations data service.
|
| About once a month I would get "the customer says we're
| showing London Airport in the wrong country and they want
| it fixed NOW." To which I'd respond "There is no airport
| named London Airport, can you please include the IATA Code?
| Are they referring to LHR London Heathrow Airport which our
| system has in London, Greater London, England. Or are they
| referring to YXU London International Airport, which is
| located in London, Ontario, Canada? Or ELS East London
| Airport which is in East London, Eastern Cape, South
| Africa?"
| thundergolfer wrote:
| > The best method I've found (though there's probably a
| better one) is to just suggest one or two of those
| checklist items during that conversation.
|
| Yeh this is what I do. Mention (in a friendly way) the
| specific checklist violation and then at the end link to
| the full checklist if they're curious.
|
| My previous workplace also linked it in onboarding I
| think.
| vsareto wrote:
| >It's just so disrespectful
|
| I think you're seeking that out. Someone more relaxed might
| just respond with "what's it doing?" and let them share the
| details. Some people chat over messengers like they talk in
| real life and you can learn to cope with both styles.
| DSMan195276 wrote:
| I agree to an extent, I think it just has a lot to do with
| knowing your audience and meeting them where they are. Frankly
| nobody wants to read a book of a comment and don't always have
| the time anyway (so they just won't read it all), so while it's
| important to include relevant information and avoid
| ambiguous/unclear language, it's also important to keep it
| concise rather than just spitting out as much information as
| you can (as I frequently see people do).
|
| The author was definitely getting at this, but (ironically) I
| think they should have called it out a bit more. It's not about
| writing as many words as you can, it's about writing _as
| little_ as you can while still making your point clear and
| including all the information you think the reader needs.
| TremendousJudge wrote:
| Yeah the REST example makes this painfully clear. Donwright
| assuming he doesn't know and writing an education explanation
| on REST to anybody except a junior developer can be downright
| offensive. And many times (especially when working remote!)
| you're interacting with devs you are not entirely sure who
| they are.
| ramilefu wrote:
| 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.
| throwawaysleep wrote:
| > 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 wrote:
| 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.
| batesy wrote:
| Seems like a pretty significant opportunity to level up for
| those willing?
| soneca wrote:
| 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 wrote:
| On the contrary, a lot of businesses punish it.
| ramilefu wrote:
| Certainly. I've leaned into it, when given the chance.
|
| As the author writes, it definitely makes you stand out, if
| you are willing.
| devonkim wrote:
| 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 wrote:
| > 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.
| Multicomp wrote:
| > 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.
| P5fRxh5kUvp2th wrote:
| 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 wrote:
| 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.
| Nextgrid wrote:
| 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).
| Jensson wrote:
| 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.
| markrages wrote:
| Sometimes I get the feeling that many developers are
| functionally illiterate. (In the
| 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 wrote:
| 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.
| hbrn wrote:
| 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 wrote:
| > 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 wrote:
| 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
| hbrn wrote:
| > I like written communication, it forces you to be more
| structured in your thinking
|
| It sure does, but I don't care if comms are unstructured if
| same job gets done much faster. You're not going to frame
| your structured communication and put it on the wall. You
| could argue that someone might find your past PR
| communication useful in the future, but that's what code
| comments are for.
|
| > a review that can be done in a slack hurdle in 15 minutes
| can be done async in less
|
| Strongly disagree, some code reviews have lots of back and
| forth. A branch that could be merged within an hour may
| take several days because reviewers and branch owner each
| going at their own pace. The more async you are, the more
| WIP you're going to have, and it is always a bad thing.
|
| > every one of these hurdles will actually be surrounded by
| a period of non-productive time
|
| I consider time spent getting on the same page with my team
| members to be one of the most productive things I can do.
| Even more productive than writing code.
| ngrost24 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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"?
| xbfjvusb6 wrote:
| It's a black box but the CEO has communicated dev
| performance is dependent on amount of code shipped. I
| suspect they're using sloc or pr counts behind the
| scenes.
|
| I've done everything you're recommending. CEO doesn't
| care about any of that. Only metric they care about is
| money made and code shipped.
|
| They do say they care about communication and apparently
| track it but I havnt seen it reflected in comp reviews so
| my conclusion is code shipped is the only metric.
|
| We have sloc and pr tracker stat pages so Im making a
| guess they are using sloc.
| Ensorceled wrote:
| > 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.
|
| Both are 10x developers. One by 10x impact at the code level,
| the other by 10x impact at the "delivering the right thing
| the first time" level.
|
| Though, in reality, it's really hard to be a 10x developer
| without doing both of those things ... a profilic coder who
| is solving the right problem because they took the time to
| communicate and understand the real issues.
| SpicyLemonZest wrote:
| It's interesting, because I've heard a lot of stories about
| environments like that, but I've never personally seen one.
| In every job I've had, the most respected (and highest paid)
| developers have always been the ones who struggle to find
| time to write code because they're too busy communicating. It
| was actually a hurdle for me at the start, and I remember
| being shocked the first time a manager told me writing lots
| of good code wasn't enough to get promoted.
| scruple wrote:
| > 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.
| PragmaticPulp wrote:
| > 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.
| 451mov wrote:
| > Communicating effectively as an engineer means empathically
| increasing the resolution of your writing.
|
| What does that even mean?...
| lordswork wrote:
| 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.
___________________________________________________________________
(page generated 2022-10-28 23:00 UTC)