Recently, I had a small debate with other leaders on the impact of communication and its role across the team. We debated that repeating material in the town hall format adds no value and that they would prefer smaller more personal modes of communication. I believe that we need to communicate widely and personally. The value doesn’t come from new information but from the data (or the problem) being presented differently.
When I chat with my team, I sometimes pick up signals of things that have been misunderstood, whether from an email, a formal socialization, or a group meeting. Often, the presenter hasn’t fully formed the story, or they haven’t followed up with additional reading, and lastly, maybe the person hasn’t aligned fully during the meeting (with follow-up MoM for confirmation).
What I hope you get out of this is that communication is critical for your journey. You’ll learn about the rule of three, storytelling, confirmation, explicit and implicit communication, how values influence communication, Amazon’s way, the recurring nightmare, and technical communication methods.
Repeat x3
I read this somewhere long ago (so I can’t cite it correctly), and it’s probably a mix-up of rules. It’s said that we must repeat ourselves (at least) three times. We also need to use (at least) three different modes of communication so people can absorb what we’re trying to get them to do. This could be an initial socialization town hall setting, a follow-up email with more details, and a Slack reminder to read further.
Repetition is the key to getting your core message across. What each person will get from each repetition is something different. If you remember from your learning days, there are four types of learners: visual, auditory, reading/writing, and kinesthetic (doing). When you want to impart your knowledge or teach your team about the direction, ideally you should try to incorporate all these learning methods.
The visual and auditory methods will be the most common (for onsite) teams. These will be your town halls and follow-up meetings. The reading and writing will come from asynchronous communications like blog posts, RFCs, or ADRs. Finally, especially if it’s a new process, the last method will come from the actual doing and the reinforcement.
Storytelling
The job of a leader is to sell a story. You must onboard your team to whatever pivot, process, or product you’re working on. You’re here to get everyone on the same wavelength and have the same basic understanding of what you want to do and why. Imagine you’re on a ship – you’re the captain. You tell your crew where to go. If you don’t align on which side port is and which side starboard is, the engineers might send your ship in circles when you send directions across the boat. I imagine those ancient ships where a navigator on the deck called down to the engineers in the engine room to add more power to the left or right propellers.
What do I mean by selling a story (instead of telling a story)? Leaders are some of the most excellent salespeople out there. We sell a vision to motivate our teams and get them on board. We sell the future. We must convince our teams to hop on and trust us and our direction, wherever that may lead.
Now, I’m not going to describe storytelling methods here. But always remember that you need a beginning, middle, and end. It also helps to tell people what you want to say upfront and finish with what you’ve just told them. Stories must be engaging and tell people what to expect (no surprises). Storytelling is probably as old as the human race and is a skill we shouldn’t forget.
In the corporate world, storytelling also means structure. This is where the McKinsey Pyramid Principle will help. It’s a simple concept whereby you start with the answer and then break that down into its data and run through each of those concepts with the supporting evidence. The principle also begins with the SCQA.
- Situation: Set the scene with some facts. These are things that we will all agree on relevant to the situation.
- Complication: Introduce the problem.
- Question: What’s the question that will be on everyone’s mind?
- Answer: Your answer to the question.
You can use the SCQA in all forms of communication and not just presentations. This will allow you to craft powerful stories and deliver crisp information to your team.
Confirmation
Confirmation is an essential act of alignment within an organization. You need to understand that all parties are in complete agreement and alignment and fully comprehend what the other party is suggesting; otherwise, you’ll end up in a situation where expectations aren’t met.
This can be done with active listening and repeating back (in your own words) if you’re in a meeting to confirm your understanding of what the other person wants.
You can send an email after the meeting with what was agreed (or minutes of the meeting if you have that) and what the next steps/action items are. By doing this, you are creating an explicit alignment between the parties and setting expectations. You’ll know if there’s a misinterpretation (as they’ll reply with an escalation).
Explicit, Implicit
I prefer explicit communication over implicit, but there is a case for both. What is the difference I hear you ask? Explicit communication is very direct and addresses the issue/problem/solution with clear (cannot be misinterpreted) language. Implicit communication on the other hand is the opposite whereby you will omit the exact issue/problem/solution and try to use language to “muddy the water.”
When might you use explicit communication? I use explicit communication to set expectations for my team or create alignment across the organization. Explicit communication is almost always the best communication strategy. Be straight to the point.
How about implicit? In general, I use implicit communication when I want to talk about sensitive topics. This could be a company-wide initiative with legal ramifications or issues that could be culturally insensitive to groups. Implicit communication tends to favor codenames for projects so that if it’s overheard, you need to be involved in the project to understand. Take an example: you’re working with a global bank, and this bank offers interest-earning bank accounts. It’s haram to earn/take money by just having money in Muslim cultures so it might be insensitive to talk about this in countries that are Muslim.
Values
Whenever I talk with my team, I always start with the number one value for me. I will never lie to them – especially when they ask me about challenging issues. However, I will tell them if I cannot say more. If they ask for feedback on a presentation, I won’t sugarcoat it if I thought some places were lacking. This direct feedback helps my team grow far more than following an “ice cream sandwich” approach, whereby feedback may be lost in the compliments.
Values will influence how you talk and act. Be careful when projecting your values onto others’ communication. They may have the value of being friendly and will not give direct feedback but offer indirect advice. It’s okay to have different values as long as you respect them and they respect you.
As a leader, your team will look to you for company values. Do you follow what’s written down by the company? How do you celebrate and reward those who follow the values? You need to “walk the talk” and lead from the front by following those values and creating a culture that follows those values.
Amazon’s way
I do think Amazon did something right here, especially now given the cost of engineering and product teams. What did Amazon do? They effectively banned presentations in favor of written documents that outline the meeting’s topic in five pages or less. Do I agree to everything? No. Sometimes, presentations are a valuable communication tool.
My takeaway is the importance of setting the agenda upfront and preventing surprises. By having everyone in the room understand the context of the meeting (or spending the first ten minutes), we will have better discussions than one person leading the meeting while others play on their phones. Does it need to be a lengthy document? No.
The other reason I find Amazon’s communication method valuable is that it gives the person who set the meeting a chance to write down their thoughts concisely. We can effectively “think” by writing. We can organize our thoughts before wasting everyone else’s time. With this method, you learn how to structure your content so that it’s easily digestible by everyone. You’ll also learn how to write clear and engaging pieces.
Avoid Recurring meetings
I avoid recurring meetings that aren’t 1:1s. Any team update meeting can usually be turned more effectively into asynchronous notes. While this rule is often broken (sometimes unavoidable), it has become a time saver for me. You can usually find out by asking if you need to be in a meeting.
This will also help to get rid of “looking busy” work and help you focus more on deep work, whatever that may be for you as a leader. Getting rid of busy work will set an example of how you want to communicate and let others know your time (and theirs) is valuable.
Maker vs Manager
Hopefully, as a manager you’ve heard this term before; if you haven’t, there’s a basic explanation. A maker spends their time “making” things – i.e., a software engineer. A manager is someone who managers people – i.e., a software engineering manager. Each of these roles has distinct ways of seeing their time.
Makers see their time as valuable, finite, and their own. They can either spend it making things or not making things. Every meeting they attend subtracts from their creative flow, and each interruption sets them back to square one on their task.
A manager sees their time as given and not owned by them but rather freely given to others to enable collaboration. Every meeting adds to the base alignment and confirmation that we’re working on the same thing and towards the same goal. Managers can switch context because their mind is on the system rather than the task.
If you technically imagine this, a maker is serial focusing on one task at a time. A manager is parallel and concentrates on everyone’s tasks simultaneously.
Technical Communication
I have a separate section here for technical communications because we like to do things slightly differently than other business functions. I’ll cover methods of communicating technical architecture, new technologies, fundamental knowledge, and what-to-dos.
Sharing Sessions
Sharing sessions (brown paper bag sessions or tech talks) are our way of sharing knowledge. Often, I don’t see this shared across other functions as part of learning and development. This is a session whereby the presenter will share a topic they are a specialist in or have recently done some deep dive into and want to share with the rest of the team. These presentations are thirty minutes to one hour depending on how deep the speaker wants to go.
Within sharing sessions is a sub-cultural method called lightning talks. These are ten-minute presentations on any topic the engineer is passionate about. I like this method as it allows for less formal talks and more free-flow conversations. The focus tends to be on the topic and is usually audience-directed (via a Q&A session afterward). It’s also easy for beginner speakers to start with as there’s not as much preparation work required.
Hands-on Labs
The best way to ensure that we touch all aspects of learning is by doing. Hands-on labs require engineers to teach each other new technologies by doing the work. These are crafted sessions where a goal, some direction, and a starting kit are initially given. After that, it’s exploratory work that follows rough instructions designed to get the engineers thinking and learning, creating new neuron connections (synapses).
With hands-on labs, the goal is to communicate through learning. We propagate the knowledge so that we don’t have any bus factor within the company. An example of a lab might be to set up an Observability (e.g., NewRelic or Datadog) agent on one of their services. The engineer might not know this, and the training wheels approach here helps.
ADR, RFC
An architecture decision record (or log) and an RFC (request for comment) are designed to ensure quality in our work and give future maintainers an understanding of what, why, and how we’ve built what we’ve made.
An ADR is typically stored where the code is stored (in a version control system) so that all historical changes are recorded and logged. Each commit is typically one decision record, allowing maintainers to quickly see where and when particular architectural decisions were made. I want to note that ADRs have been hard to maintain in practice as engineers sometimes aren’t consistent with documenting their findings.
An RFC is stored in an internal Wiki to be easily searchable within the company’s knowledge base. Typically, one RFC per document assesses various possibilities for each decision and records the chosen one. By being on a wiki, we also allow for asynchronous collaboration (comments) and the team works together to find the best, more practical solution. In my experience, RFCs have been successfully adopted, especially if as a leader you endorse them. They capture the architecture knowledge before a project starts and allow for conversations to follow.
Ideally, you only need one of these solutions to add quality control to your architectural process. The peer review process will allow the capture of missing requirements, alternative solutions, and best practices establishment.
Service Documentation
When you look across your vast array of microservices, do you know what they all do? Do you think a new joiner will understand what a service does by its name? Service (API and component) documentation is designed to solve that.
Interestingly, there are now a lot of tools available to help with the discoverability of services and their APIs. We have things like BackStage and OpenAPI (Swagger) designed to bring all this helpful documentation into an easy-to-use central knowledge repository. Besides that, do you know how every component works for the front end? We also have tools for that like Storybook.
Service, API, and component documentation are living documents, meaning what you see today may change tomorrow. They are designed to stay up-to-date with the current development of your teams. Ideally, these tools are designed to be as close as possible to the source (your code).
Readme
Why is desktop computing/remote development setup becoming more popular? It is likely because codebases are too massive or complex to set up a local environment to run all the required components/services. However, readme’s still have their place.
A readme is a document stored with the code (usually in plaintext). A readme helps engineers understand how to build, compile, and (potentially) deploy the code. It may also have some FAQs on how/where to get started and what tools you need.
Readmes are placed in the repository’s root folder and are the first thing you will see on most browser-based git exploratory tooling. In open-source software, these are critical technical documents describing the project and (potentially) the contributors and the license.
Product Requirements Document (PRD)
While technically not from the technical team, it’s a crucial document for alignment within product engineering. A PRD describes all aspects of the feature the team wants to develop and gives an overview of why we are developing the feature. You’ll find in early startups these documents don’t exist because the engineering and product teams are so small that they can talk it over and are all aligned on the business’s goals.
PRDs are working documents, meaning they will evolve as the product evolves and shouldn’t be considered static. Hopefully, over time, you’ll see a good definition of the product/feature which will help engineers understand what you’ve developed and why.
Runbooks
Runbooks are the ways teams communicate how they operate in production. These documents describe what to do in specific scenarios or situations. For example, you might find there is a runbook for rolling back a service in production, or there is a runbook for specific on-call issues that are common, or lastly, there might be a runbook for scripts that need to be manually run.
Runbooks are essential as they help communicate the team’s standard operating procedures and reduce the chance of something going wrong. They also help onboard engineers into on-call situations by guiding them on what to do without taking time from other engineers.
Code Reviews
Code reviews can be done asynchronously or synchronously (pair programming). These are probably the primary way engineering teams will communicate daily. The code base is where we spend most of our time, so it makes sense that engineers also communicate through code.
There are many ways to go about code reviews, and there is a lot of advice around them, too. They can be a way for senior engineers to mentor junior engineers on standard practices like SOLID (or GRASP) if using OOP. Code reviews also help pick up on optimizations or architectural faults. If asynchronous, they help with written communication and thinking by writing (and how to give feedback). When they are synchronous, they help foster trust.
Code reviews also help maintain the quality of the code by having multiple pairs of eyes on it. By slowing down, you speed up (less rework and bugs).
Linters
I’ve chosen to include linters here as they are a form of non-verbal communication from the development team that guides engineers regarding how their code should look. Linters automate away the teams’ nitpicking about how to decorate code. It’s a form of communication that allows the team to express itself.
Diagrams
Diagramming, whether flow charts, architectural diagrams, swim lanes, or any other diagram is crucial in unlocking a collective understanding of a problem. I’m a visual thinker, and diagrams (whether in my head, on paper, or a whiteboard) help me understand context quickly and make decisions. We represent components in boxes with lines and arrows to help us understand the flow of information and how components will interact.
Data can also be represented by diagrams. This helps us understand the relationships between data and how to design extendable solutions. By visualizing the data, we can find gaps in our understanding and know where we can normalize if it makes sense in that context.
Architecture as a diagram is almost always given. Visualizing how the components interact, especially in the cloud, where you can have native architectures that may get complex quite quickly can help. Most likely you’ll be dealing with microservices if you have many components. Keeping it all in your head can be messy, especially if you’re using event-driven design, whereby the components will be highly decoupled.
Lastly, understanding the flow of information and requests is essential, especially at scale, where things are more likely to happen in parallel, and you need to ensure no race conditions exist.
So, you can see that communication via diagrams is essential to understand the nuance and grasp software engineering concepts. They help others visualize what you see and align everyone towards the same goal.
Communication is Everywhere
We shouldn’t just consider conversation communication. You’ll find written documentation for software engineers as important as verbal communication from management. As a software engineering organization leader, you must ensure your message is understood. Repeat it as often as you can and confirm the understanding. Learn the art of storytelling and stay true to your values while respecting the values of others. Understand the difference between explicit and implicit communication and when to use it.
Use written words to help set meeting agendas and create a shared understanding (Amazon’s way). Writing will help you think and clarify the meeting goals. Avoid those recurring meetings that add no value. Can they be async? Lastly, you should understand the difference between a manager’s communication expectations and a maker’s. Use everyone’s time wisely.
Software engineers have a lot of written communication as part of their daily routines. A lot of context, art, and science go into our making of software. It’s also not done in a vacuum, so we need to share a lot of knowledge (especially as knowledge workers.) This is a team sport, and as leaders, we must prioritize transparency, support, and communication to enable better outcomes.
Thanks to Shawn Lim for helping me review this article!
Leave a Reply