Learn to communicate

David Martín Alaminos — Sun, 05 Jan 2025 14:26:38 +0000

In my experience as both consultant and in-house engineer, tech organisations often falter from communication issues, rather than from challenges related to the technology itself. There are two forms of communication: spoken and written. I've already shared some thoughts on the latter, like on the importance of tracing knowledge, so now I'd like to focus on the spoken form. In my opinion, it's the harder one to master: unlike a piece of text that we can always revisit and learn from past mistakes, a sentence said out loud usually cannot be revisited (or even remembered!). So how can we possibly improve our spoken communication?

My spoken communication skills weren't particularly good during my first years of professional experience. Naturally, I just didn't realise about it back then. I was capable of giving a successful public talk —always well-rehearsed— but sometimes I would have to explain myself twice and even thrice in order to clearly convey some technical ideas to my team. Sometimes I would pitch an idea, only to be initially disregarded and later recognised after a colleague had reworded it. It felt frustrating. The first step to improve communication is self-awareness: I realised about certain patterns in the way that I communicated, or in the way that my words were received.

In my years working at ThoughtWorks I had the luck to work with extremely talented and passionate people, and looking back, I realise that the feedback culture there was the game-changer. Let me describe it briefly: everyone in the team had regular (usually monthly or biweekly) feedback sessions with everyone else in the team, regardless of role, seniority, and whether they were a Thoughtworker or a client. In those feedback sessions, I would meet my colleague, sit together somewhere quiet (or virtually), and then exchange pieces of feedback that we would have prepared for each other, since our last feedback session. We could also ask to focus the feedback on specific topics that we wanted to track. It was common to take notes on the feedback received, and later reflect on it and decide whether to address it or not, and if so, decide what actions to take. This all happened organically among teammates, without any dictated rules or structures. As you can imagine, it was a prime opportunity for me to focus on improving my communication. I was full of determination and worked hard until the regular and diverse feedback supported a new evidence: my communication skills were improving!

Today I'm still not a master in communication, but I feel proud when I look back and see my evolution. For you reading, and perhaps feeling some words resonate with you: here are some pieces of wisdom I've gathered on my way. Take them with a pinch of salt, what helped me may not necessarily help you.

Ask for feedback

Feedback is the simplest, yet trickiest tool you can use to improve. It's tricky because it requires you to openly speak and listen about your vulnerabilities, and at the same time your colleague must be able to be completely honest with you. Feedback is a great measuring tool to compare your current status with your past self. I like to write down and archive the pieces of feedback I receive, sometimes adding a summary of my thoughts and possible ideas or plans to improve myself. Depending on the topic, feedback can be quite subjective - so having several sources can help reduce biases.

It's important to separate feedback from advice (facts about you from your colleague's point of view versus what your colleague would have done differently, in your shoes). You don't have to take advice from your colleague unless you explicitly ask for it.

Journal your progress

I find it fascinating to document different things from my day to day. Perhaps a presentation I've done for the client, and what kind of questions did I receive. Perhaps something as simple as an interesting conversation with a teammate, sharing ideas on how to solve a complex problem. How did it go? Was it as expected, anything surprising happened? Was I able to convey my thoughts clearly? How did I feel afterwards?

Remember to check some old entries in your journal from time to time, it's a nice feeling to see an evolution in yourself, new patterns emerge and how different topics come and go as you move on.

Look for non-verbal cues

Make a conscious effort to watch for non-verbal cues in the people you're talking with. For example, if they are squinting their eyes or tilting their head slightly, perhaps your message is not getting through. Perhaps you're boring your listeners with unnecessary or redundant information, if they're looking around or switching their attention to something else. Be aware that this kind of cues are highly dependent on the local culture, and even on the distinct personalities and expressivity of your colleagues, so it's not an infallible method. Still, being able to notice certain gestures can reveal the disposition of your listeners, and even hint you to adjust something in your way of communication.

Listen to your own communication

Sometimes I make a voice recording of myself explaining a problem, talking through technical concepts, or pretending to convince someone about my approach, when I'm alone in the room. Wait a little before listening to the recording, and try to analyse it critically, as if it came from someone else. You might realise that it's not truly accurate with what you originally wanted to convey. Discover how subtleties in your tone of voice could make the message clearer or more convincing. Perhaps the message is not structured enough or is missing a logical order. And now, being aware of those weaknesses, record yourself again!

As mentioned, I only make those recordings when I'm alone, talking to myself. If you'd like to record part of a conversation or interaction with someone else, make sure to ask for permission first.

Stick to the same vocabulary

In the technical world we often use precise vocabulary to describe domain concepts, patterns, ideas... introducing synonyms in your context of communication can lead to confusion, especially if there's already a widely used and accepted word for it. I've seen many times developers talking about X, and some other roles talking about Y, when X and Y are essentially the same. Sometimes worse, people believing X and Y are the same, when they aren't. For that reason it's important to challenge new diverging words as soon as they appear. Having a common, ubiquitous language is an enabler for effective communication inside tech organisations.

Repeat yourself

We developers are quite familiar with principles like DRY (Don't Repeat Yourself) that reduce duplication in codebases, positively increasing their maintainability. But I recommend the contrary when it comes to verbal communication, particularly when conveying an important idea or when trying to make a point. Present it, and then explain it in a different way, including some other nuances. Throw in an example, perhaps. If done properly, each repetition should align more your audience with the exact concept you have in mind. Beware though, over-repetition can be distracting, plainly boring, or directly be perceived as patronising. Don't overdo it, make sure to know your audience and keep an eye on non-verbal cues.

Practice story-telling

I found this very useful to give structure to my discourse. Explaining something like a story is also helpful for keeping your listeners engaged, maybe even intrigued and waiting to hear the conclusion. The STAR framework can also be used to quickly give order to your outgoing thoughts: first introduce the Situation or context for the story, then describe the Task that needed to be done and the Actions that were taken, to finally reach some Results. It'll be better if you take a moment to organise your thoughts before talking.

Use the silence

Silence could be perceived as awkward by some, but the truth is that it'll only be as awkward as you let it be. Connecting with my previous point, it's important to give structure and order when talking (except if you're voicing your thoughts out loud, of course). In cases like that, it's okay to use some moments of silence to think something through, or before answering certain questions. Make it explicit if you want to feel more comfortable, just let your colleagues know: something like "let me think about that for a second" or "give me a moment to think" should be enough. However, if you anticipate that you'll find yourself in that situation, arrange your thoughts in advance! In certain situations, you won't be able (or won't want) to give an immediate answer without thinking about it for a longer time: try to negotiate postponing the answer, hopefully thorough thought will be valued, if time allows for it.

You can also use the silence for effect, instead of using filler words between words or sentences. Those can be specially distracting in presentations, increasing the noise-to-signal ratio of your message.

Pair programming

Pair programming is a quite peculiar set-up in which quick and constant communication between your colleague and you will be more valued than elaborate story telling or quiet thinking. Try to speak your thoughts out loud without filters, focusing more on making yourself understood than on the correctness of what you say. Your pair will complement your input, and correct you if necessary. Aside from the benefits of pair programming in your output as a developer, it's a fantastic exercise that balances the effective articulation of your own thoughts with actively listening to your colleague.

Stay curious, stay humble

Tune in a curious mindset when talking with your colleagues, and give yourself the chance to indulge in these interactions. Genuine curiosity will not only unblock conversations, but it will also be perceived as a display of interest that can help you build professional relationships. Equally important, be humble and treat every opinion with respect, even if your experience gives you an advantageous position. Listen actively when your colleagues speak and make an effort to understand what they want to convey. Your attitude will make a strong difference in the communication happening around you.

Tracing knowledge

David Martín Alaminos — Wed, 06 Sep 2023 07:00:00 +0000

Every now and then, I'm reading code and stumble upon some fragment of code that seems strange: while I can quickly see what it is doing, I can't understand or remember why it is needed. Asking a colleague is probably the most effective way to get an answer or at least a pointer to the right direction. However, it's unrealistic in the long-term to think that all knowledge will survive and persist through time. Undocumented reasons and decisions above a certain degree of criticality have an impact over the code, its maintainers, and possibly over its end users. Even good documentation might get lost due to poor placement or lack of references, leaving software archaeology as the only way to understand why some code is in place.

Here are some ways to produce documentation and avoid leaving code orphan of reason, depending on the granularity of the decision behind it.

A small scope 🐜

The first and simplest way is to add a brief comment to the code explaining the why. I only embed comments in the code if I can't make the code itself more self-explanatory by means of refactor, descriptive names and encapsulation. There is a cost in maintaining comments in the code, as they can easily fall out of sync with the code. For that same reason, think critically before trusting comments – they can be less reliable than the code itself.

Usage example: commenting a counterintuitive line of code that someone could mistake as redundant or unnecessary.

A slightly broader scope 🐎

Sometimes the scope of a reason is too broad and cannot be attached to a particular symbol in the code. It's usually the case of changes spanning multiple files, as the outcome of a technical task, user story implementation or a bug fix. In that case, it's a good idea to document the reason in the issue tracker (like Jira, Asana or Trello) and reference it somewhere across the whole changeset, like in the commit message or, if applicable, in the pull request. Sometimes there are written conversations that enrich and elaborate on the requirements or the reasons for the code – don't forget to reference them if you have the chance.

Usage example: implementing an A/B test experiment that requires changes in both frontend and backend.

A broad scope 🐘

Overarching decisions trascend units of work and often have a strategic vision about the technical domain or the product. If the reason derives from a technical decision (for example, using an architecture pattern) it's a good idea to capture it in an Architectural Decision Record. Otherwise, if the reason derives from a product decision, it's best to capture it somewhere closer to the product documentation, or in a knowledge-sharing tool like Confluence. Make sure to gather input and open a space for discussion when generating such documentation, as everyone affected should be aligned and onboard with the decision.

Usage example: choosing asynchronous communication between services in order to improve resilience and scalability.

Make sure to consolidate existing documentation first, it's easy to accidentally duplicate and slowly diverge knowledge sources (xkcd comic #927)

While there are surely more ways to document decision-making and its outcomes, what I consider of greater importance is tracing and cross-referencing those knowledge sources. There should be a clear path from the code to a documentation artifact declaring its motivation or reason. How to do it? Ensure you have knowledge sources in the first place, and contribute writing and keeping them updated. Then, reference them. Mention them. Share them. Does anyone else have more context? Tag them. It will quickly create alignment and fortify the understanding of anyone looking for answers. Leave a trace of the reason that is driving you to write code.

Forem: David Martín Alaminos