[commandlinefan]

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

[squeaky-clean]

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]

> 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]

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]

You can send them https://thundergolfer.com/communication/slack/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]

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]

> 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]

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

[leepowers]

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.

[DSMan195276]

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]

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.

[sokoloff]

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]

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]

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]

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.