[ramilefu]

The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion.

I think this is the origin for much of the friction we experience in collaboration and 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.

[Multicomp]

> The writers among us are quite the minority.

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.

[Nextgrid]

One suggestion I would add is to make it easy to do the things you ask for. You're already having trouble getting your team to do it, the last thing you want is for them to have to suffer through shitty tooling to do so (and give them another excuse to skip doing 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).

[P5fRxh5kUvp2th]

document decisions and move on, why are you asking your team to write essays?

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.

[skydhash]

Very much this. I like to write my documentation in Markdown because it allows me to be fast, while still having some structures. Then I paste the draft in Google Docs when I want to share and have people comment on it. Tooling matters and if I'm the one doing something, I want to actually choose how I'm doing it.

[ngrost24]

Personal opinion or anecdata: Is it possible that communication is "detested" because it's not valued within the developer group? Many times, when someone speaks of a 10x software engineer, the gut feeling is of someone that provides the output (measurable in code) of 10 developers, not that he's able to have an impact in the organization through communication as 10 developers (breaking silo-s, syncing teams, etc), although this might be closer to the truth and what the duties of some staff and principal level developers includes.

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.

[xbfjvusb6]

This. I can tell HR, my lead and skip about how good my communication, soft skills and team work have been this year but come comp review they don't give a crapola about any of that. All they look at is how many sloc I've shipped.

[scarface74]

For context: I never really cared about yearly reviews or raises at my job before my current job. I knew they were going to be mostly shit anyway and that I was better off job hopping every couple of years to get a “raise”. Which I did six times between 2008 and 2020 after staying at my second job 9 years and getting 3% raises and seeing the bonus drop.

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”

[karmelapple]

I'm fascinated: does your company/manager truly track SLOC and promote based on that?

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

[xbfjvusb6]

It's a black box but the CEO has communicated dev performance is dependent on amount of code shipped. I suspect they're using sloc or pr counts behind the scenes.

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.

[karmelapple]

Yowza. In that case… time to look elsewhere. I can tell you many companies do not do this sort of thing.

[xbfjvusb6]

I am. Only issue is that it isn't the worst place I've worked and it's hard to find better than what I have where I'm at.

[SpicyLemonZest]

It's interesting, because I've heard a lot of stories about environments like that, but I've never personally seen one. In every job I've had, the most respected (and highest paid) developers have always been the ones who struggle to find time to write code because they're too busy communicating. It was actually a hurdle for me at the start, and I remember being shocked the first time a manager told me writing lots of good code wasn't enough to get promoted.

[Ensorceled]

> Many times, when someone speaks of a 10x software engineer, the gut feeling is of someone that provides the output (measurable in code) of 10 developers, not that he's able to have an impact in the organization through communication as 10 developers (breaking silo-s, syncing teams, etc), although this might be closer to the truth and what the duties of some staff and principal level developers includes.

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.

[throwawaysleep]

> Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion.

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

[markrages]

Sometimes I get the feeling that many developers are functionally illiterate. (In the https://quoteinvestigator.com/2012/12/11/cannot-read/ sense.)

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.

[justin_oaks]

That's probably about right. But it's not isolated to developers. Most people skim or skip most instructions, documentation, warnings, etc.

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.

[PragmaticPulp]

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

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.

[scruple]

> Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion.

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.

[FoomFries]

I would love to hear some resources for improving. Separating the chaff from the wheat on resources is always difficult for the layman, similar to learning an instrument for the first time. Most things I find on improving writing is related to fiction, and other areas of improvement seem unnecessarily anecdotal or story driven.

[devonkim]

The issues I have are that developers tend to be bad at communicating even with each other. Communication as a discipline is a lot about meeting people where they are and this is difficult for basically everyone. The antagonistic attitude that developers seem to develop happen across almost every technical discipline whether it’s engineering or even trades. It may be even worse in trades given so much contact with the general public. If developers had to do customer support for their products as a rule you bet they’d get grumpy. However, I’d also say that interacting with the public probably makes most people in US retail grumpy, too.

What I think I’m trying to say is that developers self-selecting out of things thinking they’re either not good at them or because they don’t like to do them is a bit of a luxury compared to most professions and many on the outside would look at that and feel there’s an attitude of arrogance and entitlement as such.

[frenchman99]

> If developers had to do customer support for their products as a rule you bet they’d get grumpy.

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.

[devonkim]

The data I’m seeing is from studies showing that developers doing peripheral duties and getting interrupted is one of the biggest barriers to productivity and quality among developers rather than training, education, or even raw IQ.

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

[frenchman99]

It is perfectly possible to do customer support on a specific schedule so that it doesn't become an interruption though.

[devonkim]

Of course it's possible but the usual workflow of those in customer facing positions tends to be interrupt-driven rather than polled like how developers tend to prefer to work (and there is definitely plenty of study on context-switching productivity loss, stress, etc.). Additionally, the amount of time available for developers to work with customers must be balanced with duties like feature delivery among others. Working across n different customers with m different needs even if time boxed to n hours / week you'll be likely left with customers that feel frustrated and that developers are disengaged when they're just overworked like everyone else.

[hbrn]

Spot on. But it's not even about writing. Developers hate communication, in any form.

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.

[skydhash]

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

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.

[chrisweekly]

Agreed; even further, the presence of even a small number of interrupts can disrupt the extended focus and context-building that are required to solve gnarly problems. See also pg's famous "Maker's schedule" post:

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

[hbrn]

> I like written communication, it forces you to be more structured in your thinking

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.

[Jensson]

Developers hates communication since developers gets blamed for all communication problems even when they aren't at fault, until that changes most developers will hate it and refuse to do it since they got burned.

[batesy]

Seems like a pretty significant opportunity to level up for those willing?

[soneca]

It definitely helped me a lot in my career. It is hard to single out its impact, as good writing also help me demonstrate other non-technical qualities like diligence, trust, problem-solving. But I might take a guess and say that about 30% of my salary is due to good written communication skills

[KptMarchewa]

On the contrary, a lot of businesses punish it.

[ramilefu]

Certainly. I’ve leaned into it, when given the chance.

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