Here is my competing take:<p>The biggest problem I see in developer communication is what I call the "assumed context" problem.<p>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.<p>I'm pretty sure this is related to people "on the spectrum" often having low "theory of mind" capabilities. People without that will just assume people know what they know, and proceed to fail at communicating with those who don't.<p>It also makes it easy to think of those who don't know what is obvious to you as idiots.<p>The workaround, if you <i>want</i> to communicate with the idiots surrounding you, is to start conversations by fact finding. The question "so how much do you know about the flurbigator system?" can help.
This has little to do w/ being a developer vs. being human.<p>People joke about the programmer in a dark corner plugging away and never talking to others, but that's actually pretty rare. In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together.<p>The truth is that people - regardless of discipline - generally all want the same things from their work: to work on something meaningful, to be productive, and to be recognized for that work (both output and input).<p>That's pretty much it. If - as a leader - you can do those, you're going to generally have rather happy employees.<p>When it comes to this article, the issue is that there are a lot of people who believe that documentation and effective communication ARE necessary, but that work ISN'T recognized, and (because it isn't recognized) steals time that could be spent being productive doing something that is.<p>If you want effective communication, documentation, etc. at your workplace, it's incumbent on leadership to create that culture. Nurture it, get better at it themselves, and help those less eloquent to find their [written] voice.
As someone who went from engineering to product management, partly due to having developed a skill of communicating effectively in writing and in speech, I would suggest perhaps the most important part of communicating effectively is storytelling. If what you are sharing does not have a clear and obvious narrative arc, people are going to disengage quickly. This is not necessary for short bursts of information in a high-context environment, but any time you need to level set and share context before communicating the critical information, you should do so in story fashion.<p>If you want to level up your technical communication, I'd highly recommend taking classes in creative writing, participating in things like NaNoWriMo, or taking a class in improv comedy/theater. All of these things emphasize construction of narrative arcs and how to draw people through a story, which are essential communication skills. This gets more important the farther up the chain of command in a company you are communicating with.
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.<p>I think this is the origin for much of the friction we experience in collaboration and documentation. It’s easy to build something, ship it, and move on. That’s the dream we are sold as well: changing the world, one line of code at a time, from our basements.<p>I would love to see more focus on writing in our industry. Unfortunately, I haven’t experienced much improvement here in the last decade of working in the industry, across several organizations.<p>The writers among us are quite the minority.
Last year wrote a technical writing advice checklist for engineers called <i>How to ask for help in Slack</i>: <a href="https://thundergolfer.com/communication/slack/2021/02/24/how-to-ask-for-help-in-slack/" rel="nofollow">https://thundergolfer.com/communication/slack/2021/02/24/how...</a>.<p>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.<p>I thought about this list a lot, and believe that maintaining adherence to all 10 checklist items will dramatically improve your technical communication in chat apps.<p>For advice on writing long form communications, my absolute favorite resource is <i>LEADERSHIP LAB: Writing Beyond the Academy</i>[1]. This lecture will cleanse you of all the bad writing ideas you picked up in 12+ years of schooling, and show you actually how to think about professional writing. I've watched it about 4-5 times.<p>1. <a href="https://www.youtube.com/watch?v=aFwVf5a3pZM" rel="nofollow">https://www.youtube.com/watch?v=aFwVf5a3pZM</a>
> 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<p>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 <i>prefer</i> a short, quick overview followed by more detail <i>when asked</i>.
The post begins with a preface about promotions for leadership from the Csuite.<p>But I argue most Csuite and leaders are horrible at this too; I can't tell you how many all hands or emails I've been at where leaders use the abbreviations ELT, LT, ET, Csuite to refer to themselves -- and then use abbreviations for their move-the-needle projects and expect everyone in the room to know what they mean.<p>Clear communication is great, especially in the remote world or when dealing with complex situations. But this isn't a trait that leaders have more than developers, and it's not a trait that particularly gets you outside the development track.<p>Frankly, Ruby on Rails - and Rspec provide an example that developers should be very verbose -- in their method names, their file names, the description, background, context, and specific examples..
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.<p>Before becoming a dev I spent almost a decade training and involved in Christian ministry, a surprisingly technical field<i>. 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.<p>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).<p></i> 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.
Glancing over the examples, I don't see anything that's particularly unique to us developers. Support, marketing, sales, the bosses, our customers, they could all improve their communication in the ways presented here.<p>For me, learning how to construct simple proofs during my early math classes at uni really helped my writing. It made me pay a lot more attention to what I'm writing, like ensuring arguments are laid out in a more logical manner and that references are clear.<p>Not saying I'm exceptionally good at it. But given that language was by far my weakest topic at school until then, I've since helped both my SO and my sister gain over a full grade point increase in college on hand-ins and similar, just by looking over what they've written and doing some minor tweaks like reordering sentences to ensure logical consistency in their arguments.
This was a great read and conscious of the nuances to effective writing. Articles like these tend to have a "write this way NOT this other way" mentality. To paraphrase a comment I saw somewhere regarding code optimization:<p>"Given enough time most code can be optimized quite a lot".<p>The same can be said about writing. The audience, the topic, and the intended outcome make for a complex optimization problem that, as the author touches on, can eat up a ton of time. The PR comment example is perfect. The initial comment (on the lefthand side) works. *It does the job*, however when the author is placed in a different context (audience and intent), the comment on the right becomes more optimal. It also took 5x the amount of time to write up. I feel as though knowing the tradeoffs and managing your own time seems to be half the battle when it comes to communicating.<p>My additional advice for devs is; get honest feedback on your writing (slack messages, design documents and everything in between) so that you can learn best what works with whom.
Very good old thread on HN on similar lines (Ask HN: How to speak like a leader, not like an engineer?)<p><a href="https://news.ycombinator.com/item?id=19349676" rel="nofollow">https://news.ycombinator.com/item?id=19349676</a>
I think we overlook wordiness too often! In fact, each "good" example in TFA can be shortened without losing context:<p><i>Good:</i><p>"I checked the foobar.py script and told Sarah that there was a bug related to updating the users table in SQL — the script does not seem to update the last name column."<p><i>Better:</i><p>"I found a bug in foobar.py and told Sarah it's not updating the last name column in the users table."<p><i>Good:</i><p>"Hi team, the email sending worker keeps crashing with the following exception. I've tried re-running, clearing the cache, re-installing dependencies. Can I get a hand?"<p><i>Better:</i><p>"The email sending worker keeps crashing with the exception below. I reran it, cleared the cache, and reinstalled dependencies. Can I get a hand?"<p><i>Good:</i><p>"The resource defines two routes, but the GET handler can only handle one of those — the one without any path params. I can technically make a request GET /api/foobar/123/456 and have the app crash with a 500 because there is a route but the handler doesn't take any params.<p>Roughly speaking, there are two "types" of resource endpoints — list and singular.<p>List type resource endpoints handle
- getting a list of resources: GET /things
- creating a new resource: POST /things<p>Singular type resource endpoints handle
- getting a single resource: GET /things/123
- updating a single resource: PATCH /things/123
- deleting a single resource: DELETE /things/123<p>To handle all cases properly, you need two resources:<p>...
"<p><i>Better:</i><p>"The resource defines two routes but the GET handler can't take path params, so a request to GET /api/foobar/123/456 crashes the app with a 500.<p>There are two "types" of resource endpoints:<p>List:
- get a list of resources: GET /things
- create a resource: POST /things<p>Singular:
- get one resource: GET /things/123
- update one resource: PATCH /things/123
- delete one resource: DELETE /things/123<p>So you need two resources:<p>...
"
=== Cut needless words ===<p>The article references Covingtons How to Write more Clearly, Think More Clearly [...] Powerpoint presentation [1]. I highly recommend it!<p>A fun part in that presentation is when Covington, in a series of steps, revises this sentence...<p>“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.”<p>..Into this one:<p>“To improve your writing, cut out unnecessary words.”<p>OPs article calls for more words to provide context. But by revising you can often cut the length in half.<p>[1] <a href="https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf" rel="nofollow">https://www.covingtoninnovations.com/mc/WriteThinkLearn.pdf</a>
In my own brain I've created 3 different categories :- Others, Developers, Management.<p>I find it easier to explain stuff to other people by giving context from their field<p>For example to someone in food industry I'd say, frontend is like how you present your food at the table and back-end is like the kitchen where food is prepared.<p>To people in development what I've learnt is that you've got to find the right balance, can't dumb it down a lot or can't switch it up, always in the middle.<p>Management will understand 3 things : Excel, PowerPoint, Money.<p>That takes care of 90% of my conversation.
This is a great article with nice examples, and I like the "high resolution" vs. "low resolution" concept.<p>But it leaves off the other side of the equation: know your audience.<p>If your audience wants to read a long, detailed communication, then that's great and you should write a "high resolution" message.<p>If your audience has little time available and no real need to know the details, then the "low resolution" message is much more effective.<p>The real trick is learning how to pack exactly what the reader needs to know into a "low resolution" message.
Judging the right amount of information is what I struggle with. It's easier to judge whether someone wants more details when you're talking to them. It's harder when you're responding to a comment or in a chat.<p>When it's too little, you go back and forth. When it's too much nobody reads your novel. I tend to go into too much detail, so I'm learning go where I feel is adequate and then take a few steps back.
> It's not about you, though.. It's about them.<p>Ironically (given the context), he buried the lede.<p>That aside, if you're interested in raising your comms flag, I recently finished "Smart Brevity". As a solution, it's not a panacea for all use cases. Still, it's a quick and useful read. Simple but effective.<p><a href="https://www.thriftbooks.com/w/smart-brevity-write-less-say-more-get-heard/34185851/?resultid=d22fe885-bd5e-4105-b5df-74b939a79620#edition=61265924&idiq=52276022" rel="nofollow">https://www.thriftbooks.com/w/smart-brevity-write-less-say-m...</a><p>I'd also recommend "Words That Work" by Frank Luntz. Chapter 1 is all you need. The rest is simply the lessons from Chapter 1 in practice.<p><a href="https://www.thriftbooks.com/w/words-that-work-its-not-what-you-say-its-what-people-hear_frank-luntz/251558/?resultid=2805995f-7cd0-4c38-a44b-6f93da6b42a9#edition=4919560&idiq=3895357" rel="nofollow">https://www.thriftbooks.com/w/words-that-work-its-not-what-y...</a>
> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is.<p>Perhaps I'm being picky, but... that's also not what engineers get paid for, either.<p>I think engineers get paid to do things that solve problems. Sometimes that involves writing code, but sometimes it absolutely involves writing a Slack message, having a call, or just thinking a little more.<p>A Slack message might be, "Got a minute to chat?" to start a voice call that will clarify some requirement that's been bogged down in a quagmire of too much writing or conflicting ideas. Requirements are clarified, maybe not a single line of code is needed to be written, thanks to a better understanding of the customer's desires.<p>A Slack message might ask, "Does this change work instead?" with an image attached of a simpler approach.<p>I wouldn't typically respond to one line from a blog post, but since this was up so high in the post, I felt I needed to gently encourage a little rewrite of this sentence :)
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.<p>---<p>I usually start with a:<p># Solution:<p>With links to any tickets/jobs/etc. For example, the inverted pyramid puts the most important info first:<p><a href="https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)" rel="nofollow">https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)</a><p>Then I'll put any relevant notes and commands that I refer to as:<p># Discovery:<p>```<p><pre><code> # 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
</code></pre>
```<p>So that people in a hurry can skip the parts they don't need.<p><i>Edit: I edited this a lot, might need to refresh</i>
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.
> <i>Writing messages on Slack isn’t what engineers get paid for</i><p>This is wrong.<p>If you disagree, stop writing messages, and see how long you keep getting paid.
I have experience that suggests the contrary of his suggestions. Working in a remote culture, often we can spend too much time writing things out and in turn reading things that are irrelevant.<p>I would propose a more progressive framework: Start with the short message without any context. If needed, make a new message with all the context.<p>As an example I have a couple of times asked for help where a response would list the pros and cons of "REST" and I would have to spend too much attention reading it. Alternatively the following would have been perfect:<p>> X is hard to do in Elixir, any ideas?<p>< Defer it to our Next frontend. It is easy to do in JavaScript<p>> Thanks!
I think that short-form writing is important (I tend to prolix, so it's not my strongest point).<p>I was always told that any proposal or explanation that is to land on the desk of a VP or higher (most companies, but the one I was in, was General Manager, or higher), needed to be a <i>maximum</i> length of one page, and not dense text.<p>I have written <i>a lot</i>, over my life, but I tend to write fairly long pieces[0]. This has meant that I go fairly long periods, without writing, as I get involved in a project (like right now).<p>I've recently started a new series, entitled "shorties"[1], that will hold very brief writings. These seem (to me) to be woefully inadequate, but I'll get it.<p>A good exercise, for me, was the idea of a "mini-saga."[2]<p>[0] <a href="https://littlegreenviper.com/miscellany/" rel="nofollow">https://littlegreenviper.com/miscellany/</a><p>[1] <a href="https://littlegreenviper.com/series/shorties/" rel="nofollow">https://littlegreenviper.com/series/shorties/</a><p>[2] <a href="https://www.danpink.com/2005/05/mini-sagas-another-approach/" rel="nofollow">https://www.danpink.com/2005/05/mini-sagas-another-approach/</a>
One thing i can share from my experience is, some people communicate poorly because of laziness.<p>In this case, Even if the vague communication is understandable to you since you are aware of the dev's current WIP, pretend you don't understand and nudge the developmer to add more details for the context as necessary.<p>For example let's say your team has 5 services. The developer pings you : when starting the service i am facing this exception, tried different ways couldn't figure out, can you please help? .<p>Questions : Which service is he trying to start? Which machine is he trying to start?(local/virtual).<p>He probably doesn't mention these details because he thinks you must be aware of what he is working on. Even if you know the same, you can ask these questions and ask to mention such infos going forward to improve their communication.<p>The idea is to communicate clearly as with any developer and not to take things for granted due to laziness in typing the relevant details.
I'd argue that the <i>most</i> important thing to consider when trying to communicate effectively is this: know your audience.<p>One "low resolution" (using author's terminology) sentence might actually communicate more effectively than a "high resolution" one, given the right context and right audience. Similarly, a "high resolution" text over explain and perhaps even offend the reader.<p>In short, it depends.
This comment only applies to bug report / support request issues, but my personal rules that seem to work well are:<p>What happened? What did I expect to happen? What actions did I do to make it happen, or if it's an automated task then mention that.<p>Then list any errors/logs/etc I've already found that I think are directly relevant.<p>Then what I've already tried to fix it (if applicable). Then what I think should be tried.<p>Then any additional logs/errors/etc that I'm not sure are relevant, but also that I'm not sure are irrelevant.<p>So something like<p>"Hey I'm trying to deploy X but getting a ModuleNotFoundError for Y in the Jenkins build step. It builds successfully on my local machine. I'm running make deploy-dev and getting the error. Running make deploy-local gives no error.<p>This is the error [codeblock quote of the relevant error line].<p>Here is a link to the Jenkins output for my most recent build [link]<p>I've added the module to setup.py and I see Jenkins says that it installed the module [quote of Jenkins output line]. Maybe clearing the Jenkins cache would help?<p>This is probably not related but I see Jenkins also logged a JVM Heap Memory warning at the start of the run."
> Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Instant messaging tools are seen more as a necessary evil to get work done in a team than anything else. Because of this dynamic, there is a tendency to elide details or cut messages short, sometimes at the expense of legibility.<p>The article is long on tips for individual media without explaining <i>why</i> you'd use one over the other. Digital communication encompasses a wide spectrum of media, each with its best use:<p>- realtime/recorded text (Slack, GitHub issue, README, Comment, etc.);<p>- recorded graphics/text (PowerPoint)<p>- realtime/recorded voice (voicemail, phone);<p>- realtime/recorded video (Zoom, YouTube).<p>The most important question before you use any one of them is: why this medium and not one of the others?<p>Even the right message created well will flop if sent across the wrong medium.
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
I think some epic SE failures, the DOJ LE should get involved.<p>So the engineers' habit of providing details in written materials is indisputable potential forensic self defense.<p>Like the egg Greg in succession, he has a filmsy shell, but it protects, serves when needed.<p>My first civil engineering trainings, our department head she repeatedly stated and gave examples that 'you may go to jail if you don't follow the design rules and it failed' like this.<p>There is nothing called communication in engineer's world. That means plane fell, bridge collapse -- they are negotiable.<p>This is a community talk of opinions.
These points are generally true to anyone who ever has to write an email or text message as part of a job. This could be generalized to "How to communicate effectively as a knowledge worker".
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.<p>For what it's worth, I sometimes go with something like:<p>Update on foobar.py bug:<p>- Script was not updating last-name column in person table<p>- Notified Sarah, and Sarah will push fix soon<p>Details:<p>Blah blah blah, if you aren't interested in all these details, don't read this. But super useful if you need it.
Always worth it to spend 2-3x the time authoring a message with explicit context since it's going to save every reader 2-3x the time figuring out what you're talking about.
>>>> Writing effectively is a superpower, there is no denying it. As a software engineer, you write a lot. Most of the writing you do is for computers. Businesses, however, consist of people.<p>Someone wrote that code is meant to be read by people, and secondly, by the computer. Lack of writing skill could spell trouble for the quality of the code, should anybody need to read it, days or months later.
The first order positive and second order negative speaks to me. I prioritize the former over latter unless I am creating a demo/presentation of some kind.<p>I still see defaulting to prioritizing second order effect as a waste of effort majority of the time.
One of the issues with the effective communication listed is it takes a lot more effort.<p>It can take me up to an hour to get all of my thoughts into words organized for easy understanding. But I'm usually dealing with things much more complicated and detailed that a REST api.
People who understand the problems tend to be disinterested in those being paid to 'manage' them. I think that's the foundation for most of the issues.
Agree 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.
Developers:<p>Are short on time.
Are misunderstood/alienated by corporate.
Are bullied by The Firehose (Dev cycle).
So, how can they effectively communicate?<p>By keeping the Stable Release Humming.
> empathically increasing the resolution of your writing<p>I find this to be obnoxious and nonsensical, which, in an article about communicating effectively, is ironic.
Some really good advice in the article, and I like the examples too. I agree with the author that communicating effectively is an important skill in a developer's tool box, but the article only covers written communication. In reality, effective communication involves speaking and listening skills as well. These skills are important enough for developers that I wrote a whole chapter on communicating effectively in my book[0].<p>Here are a few more points I think are helpful:<p>* Communicating isn't just saying something. People might not understand your ideas, or they may interpret what you're trying to say in a different way. Sometimes you need to repeat yourself in order to drive your point across, and you may need to communicate your idea in multiple ways for people to really understand what you're trying to say.<p>* If possible, try not to communicate through other people. Don't ask Tim to ask Alanna to do a favor or a task that you need to get done. It may feel like good delegation, but the more hops your message takes before it reaches its destination, the more chances for the message to get distorted, like a game of telephone. Try to communicate your message directly to the intended person if you can. Sometimes this isn't possible and you need to communicate through other people though.<p>* Understand the audience you're communicating with. Are they technical? Then it's okay to use technical jargon and concepts. Are they not technical? Try to use more common terms and phrases. You may need to come up with examples and similes so it's easier for them to understand something that's technical or abstract.<p>* Clear writing is critical in code reviews. If you think a line or block of code needs to be changed, explain why in the code review, don't just say it's wrong and it needs to be changed—that's not helpful. Especially with younger engineers that could benefit from understanding why their code could be improved.<p>* If conversations turn in to long discussions on a code review, move the discussion to a video call or in person conversation. No one wants to follow a thread where two developers are arguing about whether something is right or wrong. Settle the disagreement outside of the code review.<p>* You'll be writing a lot of technical requirements in your project management system as you get more experienced and lead more projects and features. What you write in the ticket won't always get interpreted exactly how you think it will, so try to write as clear and thoroughly as possible when describing what needs to be done. Sometimes you may need to describe how it needs to be done as well if you'd like it done a specific way.<p>[0]: <a href="https://www.holloway.com/g/junior-to-senior/sections/how-to-communicate-more-effectively?ruid=6b3e0344-c60a-42c4-af5d-d7b168992127&utm_source=share_section_link&vip_code=FRIENDS" rel="nofollow">https://www.holloway.com/g/junior-to-senior/sections/how-to-...</a>