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
How to communicate effectively as a developer
111–120 of 222 posts
Re: How to communicate effectively as a developer
#112Earlier quoted context omitted.
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 s…
When you say “NT-centric culture” I think you’re talking about this, right? https://www.myersbriggs.org/my-mbti-personality-type/underst...
I assume it means "neurotypical" here.
Re: How to communicate effectively as a developer
#113Earlier quoted context omitted.
> > 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.
If anything over-communication sounds like a coping mechanism!
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.
Re: How to communicate effectively as a developer
#114=== 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
Re: How to communicate effectively as a developer
#115Last 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 ite…
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.
Thanks :) I hoped to turn my petty Slack frustrations into a helpful bit of shareable guidance.
Re: How to communicate effectively as a developer
#116Last 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 ite…
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.
Re: How to communicate effectively as a developer
#117Earlier quoted context omitted.
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.
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/em…
> 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.
Re: How to communicate effectively as a developer
#118Agree 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.
Re: How to communicate effectively as a developer
#119I'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…
> 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.
Re: How to communicate effectively as a developer
#120Here 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 mi…
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.