How to communicate effectively as a developer • Hacker News Board

Re: How to communicate effectively as a developer

#81

Post by thundergolfer » Fri, Oct 28, 2022, 4:12 PM UTC

squeaky-clean wrote: post #61

commandlinefan wrote: post #32

> 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 i…

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 breat…

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.

Re: How to communicate effectively as a developer

#82

Post by johnchristopher » Fri, Oct 28, 2022, 4:15 PM UTC

_greim_ wrote: post #74

BurningFrog wrote: post #51

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 mi…

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

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

Re: How to communicate effectively as a developer

#83

Post by jlos » Fri, Oct 28, 2022, 4:18 PM UTC

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.

Re: How to communicate effectively as a developer

#84

Post by galoisscobi » Fri, Oct 28, 2022, 4:21 PM UTC

thundergolfer wrote: post #22

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

Re: How to communicate effectively as a developer

#85

Post by jonnycomputer » Fri, Oct 28, 2022, 4:21 PM UTC

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.

Re: How to communicate effectively as a developer

#86

Post by squeaky-clean » Fri, Oct 28, 2022, 4:21 PM UTC

AlanSE wrote: post #73

squeaky-clean wrote: post #61

Earlier quoted context omitted.

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 breat…

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

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.

Re: How to communicate effectively as a developer

#87

Post by devonkim » Fri, Oct 28, 2022, 4:21 PM UTC

ramilefu wrote: post #3

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 documen…

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.

Re: How to communicate effectively as a developer

#88

Post by squeaky-clean » Fri, Oct 28, 2022, 4:29 PM UTC

thundergolfer wrote: post #81

squeaky-clean wrote: post #61

Earlier quoted context omitted.

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 breat…

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/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?"

Re: How to communicate effectively as a developer

#89

Post by mjw1007 » Fri, Oct 28, 2022, 4:31 PM UTC

BurningFrog wrote: post #51

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 mi…

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

Re: How to communicate effectively as a developer

#90

Post by P5fRxh5kUvp2th » Fri, Oct 28, 2022, 4:40 PM UTC

BurningFrog wrote: post #51

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 mi…

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.