https://news.ycombinator.com/item?id=19349676

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.

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.

The writers among us are quite the minority.

As the author writes, it definitely makes you stand out, if you are willing.

In addition, rarely communication is valued within the companies where we work. Most aspects of documentation, whether vocal or written, are hard to measure and as such are ignored when an evaluation of the "worth" of an IC is done.

Personally, I think communication is relevant, but I also think that it's hard for developers to resist the sculpting that companies deliver to the employees on what is relevant in this field.

That being said, the only formal raise/promotion process i know about are at tech companies. Promotions are based on “scope” and “impact” and not how well you code. The only time “coding well” comes into play is going from junior or mid.

Even the interviews that determine your leveling is based on behavioral interviews and system design.

I couldn’t interview for my next job and all I could put on my resume is “I wrote a lot of code”

Or is SLOC here more of a proxy for "features shipped"?

Because if this is what's happening, I'd encourage two changes:

1. Communicate differently to HR, lead, and skip - either use different approaches of documentation, or point out different aspects of your contributions 2. If trying various different approaches don't work... leave.

For communicating differently - I used to work at a large company, and our yearly reviews had places to capture accomplishments. That was a broad topic: it wasn't just features built, bugs fixed or identified, etc. It would also be totally appropriate to put ways you saved money or time on various initiatives, and I would frequently put down items like this.

How do you communicate "how good" your "communication, soft skills, and team work have been this year"?

I've done everything you're recommending. CEO doesn't care about any of that. Only metric they care about is money made and code shipped.

They do say they care about communication and apparently track it but I havnt seen it reflected in comp reviews so my conclusion is code shipped is the only metric.

We have sloc and pr tracker stat pages so Im making a guess they are using sloc.

Both are 10x developers. One by 10x impact at the code level, the other by 10x impact at the "delivering the right thing the first time" level.

Though, in reality, it's really hard to be a 10x developer without doing both of those things ... a profilic coder who is solving the right problem because they took the time to communicate and understand the real issues.

They have to write the code because that's what is demanded of them. If management would prioritize communication they would get more of it.

I wouldn’t say most developers fit this description, but there are a lot of people out there who embody this isolationist working style.

Some times they can be fit into a team’s structure if you have a constant stream of small tasks that really can fit into a queue of fully-contained tickets and the person is capable of self-managing and delivering good work at a reasonable rate. However, that’s a lot of conditions that many people just don’t meet. Often what ends up happening is that the rest of the team and the manager have to put in extra effort to work around the person’s personality, which slowly drags everyone else down.

That’s why it’s so important to screen for proper match during the interview process. I’ve seen a decent number of candidates who performed great on interviews, but couldn’t even pretend to be friendly during any stage of the interview. Surprisingly, a lot of them even seem to take pride in their demeanor.

I think there’s a romantic idea out there of coding mercenaries who show up, take paychecks in exchange for writing code in isolation until they feel like moving on. This mentality sounds great to people who dislike communicating or working with others, but it’s incompatible with any teamwork or any project that must scale beyond a single person. Most of the work I’ve been involved with has required teams and teamwork, so these people don’t really have a place in the team.

Tell me about it. I'm lucky enough to have a supportive manager when I try to define my teams fitness functions, but getting the rest of the team to engage is an exercise in patience testing on all sides.

They don't see the value in writing useless essays, shouldn't self documenting code be enough?

I don't see the value in skipping high resolution communication up front so we can all waste time reworking the same problem for the 5th time that month because we forgot what we decided the 4th time we worked on it.

Having documentation in anything Atlassian-branded (or similar garbage) is a no-no for example. That's one of the few cases where I would completely understand & support a developer outright refusing to do it.

Writing essays might not be everyone's cup of tea (personally I'm fine with it as long as it will be useful and will not just rot away in darkness forever), but it's manageable with good tools. But if I have to wade through molasses like Confluence, I'd totally understand why nobody wants to engage and wouldn't even be mad at them.

I'm generally not the kind of developer who hides in a cave, but as time goes on I understand them more and more - it turns out a lot of what these "cave" developers don't like involves absolutely terrible tooling that actually regressed over time (despite processing power and system resources constantly increasing).

Companies bitch about the performance of developers then ask them to do things like this.

What's worse is when companies give developers all the responsibility and none of the control.

And are also career incoherent and not valued.

I get measured on points per sprint. Documentation, customers, and PR review does not help me hit key metrics, which is why I do all I can to get out of it, including being bad at it so that I am not asked to do it anymore. Nobody has ever scolded me or had a performance meeting with me about botching reviews, docs, or knowledge sharing. I am never asked about these in interviews either. The questions are all technical or generic "how do you handle disagreement with a colleague?"

Going remote made it much worse, there's even more ways to avoid communication or turning it async.

The only remedy I found is actively forcing people to talk to each other, starting with yourself.

Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you.

Need a code review? Grab the reviewer and walk them through the parts that are hard to understand.

Designing a big piece of architecture? Instead of writing a thorough design doc that nobody will read, build a rough diagram and share it with the team immediately, preferably on a call.

Writing documentation? Ask your team members what they want to see in it.

Yeah, it sucks to do all of that when you're an introvert. But it gets easier with time. And hopefully you can find joy in the fact that you are delivering value X times faster.

That's not communication. That is forced socialization.

There are things that are expressed more efficiently in spoken form, but the truth is that spoken words are ephemeral and the mechanism for storing and retrieving them are cumbersome.

I like written communication, it forces you to be more structured in your thinking. And most importantly. It does not require another person to be actually present for this to happen.

> Doing a code review? Grab the reviewee in a Slack huddle for 15 minutes, it'll save time for both of you.

I strongly believe that a review that can be done in a slack hurdle in 15 minutes can be done async in less. And there is the need to actually schedule for that hurdle. And in practice, every one of these hurdles will actually be surrounded by a period of non-productive time.

Programming is thinking work. The actual coding, while visible, is the easiest part. We hate wasteful meetings because it contributes nothing to make thinking easier.

http://www.paulgraham.com/makersschedule.html

It sure does, but I don't care if comms are unstructured if same job gets done much faster. You're not going to frame your structured communication and put it on the wall. You could argue that someone might find your past PR communication useful in the future, but that's what code comments are for.

> a review that can be done in a slack hurdle in 15 minutes can be done async in less

Strongly disagree, some code reviews have lots of back and forth. A branch that could be merged within an hour may take several days because reviewers and branch owner each going at their own pace. The more async you are, the more WIP you're going to have, and it is always a bad thing.

> every one of these hurdles will actually be surrounded by a period of non-productive time

I consider time spent getting on the same page with my team members to be one of the most productive things I can do. Even more productive than writing code.

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.

Do you have data to support this?

I would love to do customer support from time to time to better understand the users of the product I work on as a developer. But that request has been denied to me many times, in multiple jobs.

To get people to communicate better, inspire them to do so and have faith in them.

Specialization of roles along with the political realities of corporations means that fiefdoms and exclusions will happen to though.

I can spend as much time as I like writing comments or design documentation or whitepapers or commit messages, but nobody reads it. Maybe they will set up a meeting for me to read it to them.

When I write documentation I hope that people will never talk to me because the information they need is already written down. But more often it's so I can redirect them to the documentation and implicitly require that they read it before they continue to talk to me. In other words, documentation doesn't usually prevent an interruption as much as it minimizes the interruption.

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.

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.

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

Very interesting. Any practical example from said codebases?

https://www.rubydoc.info/gems/rubocop-rspec/1.25.1/RuboCop/C...

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.

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.

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.

The reader then knows generally the scope of what you are trying to communicate, and the details become more approachable. That said, I’m pretty horrible at this balance as well, and often lean towards long form “walls of text” that eat office hours, then work OT to compensate.

I'll need to see whether our systems supports it.

In person or on video flows so much more nicely because you can see the effect of interaction and be cordial to each other without the paranoia and dread setting in.

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 maximum length of one page, and not dense text.

I have written a lot, 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).

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.

A good exercise, for me, was the idea of a "mini-saga."[2]

[0] https://littlegreenviper.com/miscellany/

[1] https://littlegreenviper.com/series/shorties/

[2] https://www.danpink.com/2005/05/mini-sagas-another-approach/

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.

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

That's pretty much it. If - as a leader - you can do those, you're going to generally have rather happy employees.

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.

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.

In 20 years I've only worked with a handful of developers who don't want to socialize, collaborate, or solve problems together.

These two sentences are not mutually exclusive. I love to discuss with professionals or hobbyists things that overlap with my own interests or profession. Or drink and joke with them, iow feel close. But put me in a pretty common group whose best interest are: shallow travel, second order or empty talks, etc - and I will plug away immediately, because telling them what they even laugh about is so boring would be rude.

On the contrary I rarely meet engineers that want to collaborate all the time unless they don't fit the typical profile of an engineer (usually a transfer from another industry). Engineers, much like myself, like to work alone not because we are loners but because often times so-called "deep work" requires actual quiet time. I don't like meetings, I don't like to pair unless there is some mutual misunderstanding that needs to be resolved, and I like to control my small talk (because I have a tendency to talk a lot about CS). I'm not a shut in, I just have work to do. Pairing excessively, for example, is an antipattern. When I worked in an office I would regularly leave my headphones on even when I got coffee because if I didn't someone would inevitably find a way to pull me away when I needed to be doing thinking.

There is time and place for scuttlebutt and honestly the amount of work I have to do every day leaves very little time for it. I could also be an extreme case because being introverted generally, a large number of meetings physically exhausts me. I've estimated I can make it ~30 minutes in a meeting before I am checked out.

The more rules, people, and processes that are put in my way just reduce my effectiveness. This leads to more frustration than it solves. For example, all these company parties and get togethers, "fun" meetings, etc are annoying to me because I legitimately stress out when I can't complete my work on my own (internal) timetable.

Are short on time. Are misunderstood/alienated by corporate. Are bullied by The Firehose (Dev cycle). So, how can they effectively communicate?

By keeping the Stable Release Humming.

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 items will dramatically improve your technical communication in chat apps.

For advice on writing long form communications, my absolute favorite resource is LEADERSHIP LAB: Writing Beyond the Academy[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.

1. https://www.youtube.com/watch?v=aFwVf5a3pZM

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.

(ie. I can't go to my manager only ever with complaints and no action)

Just forcing a URL, screenshot + expectation has improved reports drastically. Before, we'd get a partial screenshot that shows some random widget where nobody knows the URL it's from, or what it should be looking like, or whether it's actually something that looks wrong, or just something that's worded incorrectly, or that there should be a link on some term in a text.

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.

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:

> X is hard to do in Elixir, any ideas?

< Defer it to our Next frontend. It is easy to do in JavaScript

> Thanks!

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

This is the exact point. I trust my colleagues in asking the right questions. Unless I shut them down with a wall of chatter.

> X is hard to do in Elixir, any ideas?

< We don't really need X for now

> Thanks!

Yep, this is the "internet blog" phenomenon. The author asserts, without any evidence, that _X_ ought to be true, therefore _X_ is true.

As elaborated in another comment, I do trust my peers to point out errors in my assumptions.

"Given enough time most code can be optimized quite a lot".

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.

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.

Here are a few more points I think are helpful:

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

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

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

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

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

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

[0]: https://www.holloway.com/g/junior-to-senior/sections/how-to-...

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" message is much more effective.

The real trick is learning how to pack exactly what the reader needs to know into a "low resolution" message.

If you've written things well you can get the best of both worlds. I noticed this in the author's review example. The first paragraph gets a reasonably high resolution description of the problem, then the detail follows in the next paragraphs.

To be clear, I’m talking about business communications here (as was the article), not other kinds of writing.

In my field, at least, this is a fundamental concept that differentiates some of the best communicators.

Particularly as often the same message will be sent to multiple recieients that have different needs.

Of course you should try to structure the message so that people don't necessarilly have to read all of it.

For instance I recently sent a message about an analysis of the feasibility of changing a piece of hardware to a group that contained

* Managers * Hardware developers (in charge of implementing the hardware modification) * Software developers (in charge of adapting the software to the new hardware)

So it started with a brief summary of the idea and conclusion "yes it will work" (for the managers).

Continued with a some comments, questions addressed to the hardware team "the aproach is fine but we still need to sort out X,Y,Z"

And finished with a detailed description for the software team of how we should integrate the new hardware whilst remaining compatible with the existing.

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.

"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)

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.

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.

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.

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.

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

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.

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.

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.

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.

What does that even mean?...

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.

This is wrong.

If you disagree, stop writing messages, and see how long you keep getting paid.

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 mind" capabilities. People without that will just assume people know what they know, and proceed to fail at communicating with those who don't.

It also makes it easy to think of those who don't know what is obvious to you as idiots.

The workaround, if you want 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.

Only then can you decide how to try to communicate the rest.

[1] https://en.wikipedia.org/wiki/Curse_of_knowledge

In conversations people often say things that I have unusual associations about. My mind will start spiraling about the unusual association and I will begin an internal narrative about the new, unrelated topic without verbalizing any of it. I will continue with the original conversation with the convo partner. Then, out of the blue, I will verbalize something about the second topic and the convo partner has no idea what I'm talking about. The topics can be as unrelated as databases and the mating habits of penguins. I have forgotten that the convo partner did not take the journey into the second narrative with me.

Countdown to database of mating habits of penguins comment.

19 minutes.

Yes, that's often it. But it's also not exclusive to devs. As the receiver I've learned to say / ask, "I don't follow. Can you clarify?"

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

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

Or maybe the explanation was bad to begin with. Over communicating won't turn a bad explanation into a good one. Understanding something doesn't mean you know how to explain it to someone else.

Too true. Explaining things is hard. My gripe is mainly people's tendency to pretend they understand in perpetuity, instead of expressing a modicum of curiosity about it. "What does 'TPS' stand for actually?" As mentioned, explaining things is hard, and I think I'm not alone in needing help identifying gaps in my explanations.

That said, I also understand that there are huge social barriers to admitting a lack of understanding in the tech industry, especially for juniors.

Then when you have to go back and tell them the basic assumptions that they are wrong about, and that they have to redo tons of work, you lose a giant sum of hypothetical points

I don't think I am on the spectrum ( I mean, I guess technically everyone is, which is why its a spectrum ), but I do know that I was ..what is a good word.. chastised.. no.. maybe gently admonished for putting up very long detailed summaries with some discussion of potential risks involved in an assumed approach, potential tradeoffs and pitfalls.

It really depends on your boss, but I come from compliance world, where you do want to CYA pretty extensively.

Anyway, back to the story. I was effectively asked to keep writing executive summaries. I hate to say it, but things seldom are that simple. I can simplify it for you, but you will lose a lot of context with that. And this how we get to the situation, where only one guy in the entire company knows how X actually works with all the constraints that it brings.

Thus, the only way forward is to summerize, and then point out that there are details/nuances (but not getting into it). Only if the there's interest in those nuances, then it's relevant going into them.

Same as with physics. First you learn Newton. Then you eventually realize Einstein adds nuance to the formula. Start with Einstein and it becomes much more complex, hard to grasp and less likely you'll understand anything. And, equally important. If the receiver doesn't want to know Einstein, then no point in talking about him.

One big problem I see nowadays is that more people do not care about the details, meaning it's less useful as a communicator to communicate then - but also that people do not fully grasp as much the nuances and believe (and search for) simple answers - and come to dangerous conclusions about them. From my POV this is the danger with the attention economy, leading to Trumpism and similar phenomena.

I think people today care about the details just as much as people used to. It's just that there are so many more details to care about today.

The exhaustive CYA-flagging of risks (and similar behaviors) denotes more a problem of how incentive are aligned in that workplace rather than any lack of skill with words.

(but I lack facts, so maybe I'm equally wrong)

It seems that this chart assumes:

1. Everyone is a baby that gets their feelings hurt when you imply they might not know something they do in fact know (top right).

2. Everyone loves being alpha nerd and making people feel dumb for not knowing things they know (bottom right)

While both of those are real phenomena, they are pretty dysfunctional. Many people (most people?) enjoy genuine cooperation within a context of mutual trust, learning things from others, and teaching others who want to learn. In that context, checking for knowledge is not a slight, and assuming things "are obvious" and failing to explain them is not a flex.

> Bottom right should be "points lost" imo.

There's a certain breed of hot-shot dev who truly believes they're gaining status by making cryptic, in-the-know references, and there's another breed who falls for it. When it comes to social status games, if enough people believe it, it becomes true.

Yes, this is what I described in point 2. Again, I'm not saying it isn't a real thing. At the same time, I wouldn't call it the norm either.

I worked with a senior developer when I was a junior who would answer any question by starting from first principles.

I understand sometimes a question can betray a misunderstanding of foundational principles but this was decidedly not the case, at least in most of the incidents.

I eventually learned to just not ask him questions unless I was absolutely desperate, because it would take him 5-10 minutes to work up to the critical piece of information I was actually missing. I think he just liked to hear himself orate.

Empathy tends to drive my own novelistic explanations, not conceit. It might help to mention something if you haven’t yet. Everyone is different though.

I think his strategy had exactly the intended effect. If you had a real problem that required deep expertise, you knew to come to him.

If you didn't, you figured it out yourself, and thus grew your skills rather than having him feed you the answer.

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

(Similarly, someone elsethread is talking about how their non-developer colleagues neglected to tell them about an upcoming release. One possible explanation is that their colleagues were bad at "theory of mind", and believed that as they knew about the release, so did everybody else. But I think it's more likely that they were too disorganised to make sure that it was somebody's job to tell everyone who needed to know.)

The "theory of mind" explanation is that those developers don't understand what context other people are probably missing.

I agree that there are of course other possible reasons.

if you get an email from me, and when you want to follow up you're thinking "what was that phone number I should call?", don't worry, I have already put it in the subject line along with the person's name and the deadline

Taking "I need X next Wednesday" at face value to mean "as long as I have X by 5pm Wednesday I'm happy" is completely reasonable.

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.

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 spectrum are set up to fail by NT-centric culture. You think we're mind-blind? It goes both ways, look up "double empathy problem". It's just that most people are NT, so by default we have to accommodate your neural quirks but the vice is not versa.

I still ask if I'm not sure of someone's level of expertise - I think any reasonable person would react positively.

https://www.myersbriggs.org/my-mbti-personality-type/underst...

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.

In overstated form, my version of the idea is: “never use ‘it’”—because a student just learning mathematical language will have many different ‘it’s in mind, or, even worse, no clear idea of what ‘it’ is. (For example, I'll often see an application of the derivative summarized as “since it is negative, it is decreasing”, which is correct only if you change ‘it’s midstream—but students often don’t realize that they are, or should be, doing so.)

I was taught this is a project management for engineers course I took when I was younger: never use language that is open to interpretation. In addition to your examples, I also see this happening in meetings when engineers say a non-sprint task will be "quick." How quick? A few minutes? A few weeks? A few quarters? As soon as we started clarifying these ambiguities we eliminated a lot of misunderstandings.

I’m not sure this is a competing take vs the article. More like complementary.

The article mainly says “add more details.” Eg. Don’t write “the system is broken” be specific about what’s broken, what you did, and if you need help.

Basically, don’t assume context.

The author takes himself to be some kind of writer, so he said it in too many words.

His screenshots are the worst-case scenario of lack of context – just a couple of dozen lines of code, no information about where, in what file, in which repo, he's given.

* We both work remotely and live in different states, nowhere near each other.

By the way, I double-checked my assertion that he doesn't use words, in case there were some documents I forgot or had missed. Nope. At best, his diagrams or screenshots will have captions. Those captions remind me of the sort of useless comments we've all become conditioned to ignore.

    x = y + z; // set x to the sum of y and z

As an alternate theory, maybe they've spent a lot of time staring at the code in question and internalised the context to a point where they no longer think about it. Happens to everyone.

I have found that communicating to business folks and leaders is a skill like anything else and can be taught. Your assumption that being autistic somehow completely disqualifies one to speak competently to others is ableist and harmful.

While it is true that people who are autistic struggle to communicate with non-autistic people I would argue it is also difficult for non-autistic people to communicate with autistic people.

It is also ableist to assume that just because someone lacks communication skills that they are “on the spectrum”.

What is true is that communication as a skill is not often taught to developers.

As anyone can see, I did not write that.

I think what makes this stuff difficult is that the same word can trigger wildly different responses.

As an example, I've been working from Ireland for US multinationals for a while now. In Ireland, the word stupid means bad or crap but doesn't have a massive emotional valence.

In the US based tech side however, it was literally the worst thing one could say, I suspect because people were identifying with their ideas.

Same word, multiple different meanings lead to communication problems.

"Theory of mind" means, among other things, having a good mental model of what other people know and don't know.

Obviously, without understanding what piece of information the other person is missing, it's very hard to explain it to them.

The OP overstated things, but it isn't completely wrong to conclude the basic idea from your above statement.

Also, the OP did not say you wrote it, so maybe being less pedantic would help the situation.

From the article:

> In both cases, the example on the left is what I call “low-resolution writing”. There is very little context, too much reliance on pronouns and unclear references. The writing is not emphatic —the reader has to spend extra energy to work out what is being said

Your comment here is the main point of the article, which is a point made multiple times within it.

Because if you don't understand that, then your understanding of the problem space is not going to be sufficient for any useful purpose.

And if you're a manager, then the company fucked up by putting something technically complex within your purview.

Honestly, if someone does this to me, I often think they are the incompetent one/idiot. Teaching and ensuring understandability is a core skill (which can absolutely be learned) necessary for a functioning team.

At least the two folks I know with autism on my team have worked incredibly hard at ensuring they practice this skill, and they are some of the best developers I know, partially for that.

FWIW this idea has been losing some ground to the double empathy problem. People who aren't on the spectrum have corresponding poor theory of mind and empathy towards those who are. The problem is at least partially symmetric.

I've noticed a form of cultural cringe in developer communities where we assume that developers tend to be on the spectrum, have uniquely poor communication and social skills and cause social problems more than other working professionals. It's contrary to what I have seen in real life which is that dev teams socialize effectively and form cohesive and healthy cultures as much as any other field. That developers are usually the ones promoting better written norms and more thoughtful and thorough written communication.

The "assumed context" problem is common everywhere. Poor communication, anti-social and toxic behavior are common everywhere in most organizations. Developers are self-conscious of our poor social skills to an extent that is not matched elsewhere.

To create good code, developpers must have good "theory of mind" capabilities, because they must systematically consider what could go wrong, not only when the computer will execute their code, but also when other developpers will try to understand it. It helps them design more intuitive and safer APIs, choose better methods and variables names, etc.

The article is long on tips for individual media without explaining why you'd use one over the other. Digital communication encompasses a wide spectrum of media, each with its best use:

- realtime/recorded text (Slack, GitHub issue, README, Comment, etc.);

- recorded graphics/text (PowerPoint)

- realtime/recorded voice (voicemail, phone);

- realtime/recorded video (Zoom, YouTube).

The most important question before you use any one of them is: why this medium and not one of the others?

Even the right message created well will flop if sent across the wrong medium.

I find it easier to explain stuff to other people by giving context from their field

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.

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.

Management will understand 3 things : Excel, PowerPoint, Money.

That takes care of 90% of my conversation.

Also It's more of a analogy thing Explain stuff to them in their language.

But while writing stuff we don't know who's going to read it, so a general analogy, a bit tech stuff and few visual stuff all of these can be used.

Ironically (given the context), he buried the lede.

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.

https://www.thriftbooks.com/w/smart-brevity-write-less-say-m...

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.

https://www.thriftbooks.com/w/words-that-work-its-not-what-y...

---

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

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.

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.

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.

So the engineers' habit of providing details in written materials is indisputable potential forensic self defense.

Like the egg Greg in succession, he has a filmsy shell, but it protects, serves when needed.

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.

There is nothing called communication in engineer's world. That means plane fell, bridge collapse -- they are negotiable.

This is a community talk of opinions.

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.

Then list any errors/logs/etc I've already found that I think are directly relevant.

Then what I've already tried to fix it (if applicable). Then what I think should be tried.

Then any additional logs/errors/etc that I'm not sure are relevant, but also that I'm not sure are irrelevant.

So something like

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

This is the error [codeblock quote of the relevant error line].

Here is a link to the Jenkins output for my most recent build [link]

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?

This is probably not related but I see Jenkins also logged a JVM Heap Memory warning at the start of the run."

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.

In short, it depends.

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

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.

I'm trying to incorporate that narrative aspect into my own demos and presentations now.

https://m.youtube.com/watch?v=JC-xCXcyNXI

    "Hi, I'm from a team from far away in company land (1). I've been having an issue with your service for the last few weeks because it seemingly drops connections sometimes. I looked at your metrics and I see that this is happening to other clients as well. This issue is stopping us from deploying a change to the UI that we promised customers would go out next week (2). Can you help me debug from your side? (3)"

    "Hey boss (1). I think that I need more support on this project (2a). We originally thought it would be easy to refactor a widget into a widgetFactory, but after I investigated it widgetFactories will require a schema migration (3). I think Sarah is really good with those, can I ask her to work on this with me (2b)?

    "Apache upgrade production outage thread (123)"

Perhaps I'm being picky, but... that's also not what engineers get paid for, either.

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.

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.

A Slack message might ask, "Does this change work instead?" with an image attached of a simpler approach.

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 find this to be obnoxious and nonsensical, which, in an article about communicating effectively, is ironic.

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.

Good:

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

Better:

"I found a bug in foobar.py and told Sarah it's not updating the last name column in the users table."

Good:

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

Better:

"The email sending worker keeps crashing with the exception below. I reran it, cleared the cache, and reinstalled dependencies. Can I get a hand?"

Good:

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

Roughly speaking, there are two "types" of resource endpoints — list and singular.

List type resource endpoints handle - getting a list of resources: GET /things - creating a new resource: POST /things

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

To handle all cases properly, you need two resources:

... "

Better:

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

There are two "types" of resource endpoints:

List: - get a list of resources: GET /things - create a resource: POST /things

Singular: - get one resource: GET /things/123 - update one resource: PATCH /things/123 - delete one resource: DELETE /things/123

So you need two resources:

... "

These endpoints break REST conventions and will be harder to understand and maintain.

The convention is that GET /resources will list them, and POST /resources will create anew one. You can also use a path parameter to identify a resource you want to find with GET /resources/<id> or delete with DELETE /resources/<id>.

I find it useful for two reasons:

- maybe you parse the first paragraph and you have enough context to act, so you skip the second

- or you parse the first paragraph and form the big picture in your mind, and that will make it easier to dive into the details

I still see defaulting to prioritizing second order effect as a waste of effort majority of the time.

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.

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

Questions : Which service is he trying to start? Which machine is he trying to start?(local/virtual).

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.

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.