4 ms·

> 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

> 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.
squeaky-clean 4y ago
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 4y ago
  > 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.
deleted 4y ago
[deleted]
DSMan195276 4y ago
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 4y ago
  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.
leepowers 4y ago
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.

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.

squeaky-clean 4y ago

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 4y ago
> 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.

deleted 4y ago

[deleted]

DSMan195276 4y ago

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 4y ago
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.

leepowers 4y ago

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.