How to communicate effectively as a developer

Last year wrote a technical writing advice checklist for engineers called How to ask for help in Slack: https://thundergolfer.com/communication/slack/2021/02/24/how....

I was at Canva, a fast growing company adding 500 engineers a year, and the tenured engineers were getting hit with a lot of questions and help requests.

I thought about this list a lot, and believe that maintaining adherence to all 10 checklist 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

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

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.

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?

> Thanks!

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

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

The problem with opening with "> X is hard to do in Elixir, any ideas?" is that it shuts down any conversation about X. You've decided it's hard, but what if you're wrong? What if you could avoid X entirely by doing Y? What if the context around X makes it also hard to do in Next? Adding a little bit of context really helps open conversations.