Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to communicate effectively as a developer

karlsutt.com

Post reply on HN
Print view View original

71–80 of 222 posts

Re: How to communicate effectively as a developer

#71

Post by bragh »

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

Re: How to communicate effectively as a developer

#72

Post by squeaky-clean »

Jensson wrote: post #41
onion2k wrote: post #30

Earlier quoted context omitted.

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.

It is the opposite, being wrong is a really great way to start a conversation, people are really eager to correct mistakes.

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

Re: How to communicate effectively as a developer

#73

Post by AlanSE »

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…

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

Re: How to communicate effectively as a developer

#74

Post by _greim_ »

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

Re: How to communicate effectively as a developer

#75

Post by DSMan195276 »

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…

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.

Re: How to communicate effectively as a developer

#76

Post by roflyear »

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…

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.

Re: How to communicate effectively as a developer

#77

Post by squeaky-clean »

phinullfermata wrote: post #45
D13Fd wrote: post #29

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

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

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.

Re: How to communicate effectively as a developer

#78

Post by thundergolfer »

taude wrote: post #66
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 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/Cu…

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.

Re: How to communicate effectively as a developer

#79

Post by azangru »

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.

Re: How to communicate effectively as a developer

#80

Post by zackmorris »

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

Post reply on HN