DEVOPSdigest

Over many years of research(link is external), Anita Williams Woolley, a psychologist at Carnegie Mellon University, discovered that the qualities we often associate with great teams — individual intelligence, certain personality traits, personal motivation and satisfaction, and a feeling of cohesion and camaraderie — are not always reliable predictors of team success.

In fact, the conventional wisdom that assembling a group of superstars creates a superstar team is misguided. Similarly, it’s not enough to have a great leader for people to come together.

Teams are complex, adaptive systems featuring numerous components and nonlinear relationships that influence their dynamics. Ultimately, a team is much more than the sum of its parts and the secret to great teamwork lies in effective communication and collaboration.

Regardless of whether an engineering team is colocated, remote, or hybrid, they are susceptible to the same communication pitfalls. These pitfalls stem from inherent human and group dynamics and they can lead to miscommunication, backtracking, and misunderstandings.

Consequently, these issues often result in technical debt, manifesting as subpar architectural choices, inconsistent solutions, missing documentation, complex dependencies, and many other challenges.

The following are common communication pitfalls:

Disparate Understandings and Mental Models

One fundamental truth in software development is that no two solutions to a problem look alike. For instance, if two developers were tasked with writing a Sudoku solver, they would likely produce completely different programs. Moreover, if they collaborated, the outcome would be yet another distinct solution.

No matter how similar their end goal, their frames of reference and mental models are different, producing different interpretations and results. However, such varied interpretations can lead to inconsistent solutions that often require rework, contributing to technical debt.

The key is consensus building. Understanding and documenting a problem is not a solo endeavor. It involves gathering diverse perspectives, which sometimes diverge significantly. External input is crucial to break out of personal biases and expose innovative approaches — finding the proverbial "unknown unknowns."

Effective system design requires consolidating these diverse viewpoints to articulate a well-defined problem statement and feature requirements that everyone can align with. This foundation ensures the problem is fully understood, making it easier to tackle, and sets the tone for the entire project lifecycle.

Undocumented Individual and Team Knowledge

There are two forms of informal, undocumented knowledge: tacit and tribal. Reliance on these can hinder the efficient maintenance and evolution of software systems, creating bottlenecks and single points of failure that contribute to technical debt.

Tacit Knowledge

It's a misconception that productive developers are always actively coding. In reality, much of their time is spent thinking about solutions: they read existing code, understand requirements, research and validate system designs, and test various solution hypotheses. All these activities — reading, researching, understanding, deciding, confirming, validating, verifying, debugging, testing, compiling, running — are often "invisible" because they may result in only minimal changes to a code base or no changes at all!

This "invisible," often undocumented work, whether it's validating system designs, discussing problems with colleagues, or hypothesizing potential defects, significantly contributes to an individual’s insights and skills, shaping their tacit knowledge.

Consider an experienced developer who has worked extensively on a critical product component. Over time, they gain an intricate understanding of the code's details and achieve performance improvements through subtle optimizations. This expertise, which includes knowing how different parts of the codebase interact, optimizing algorithms for specific scenarios, and managing complex dependencies, is based on personal experience and intuition.

It may seem an easy solution to just message the expert developer whenever you have a question, instead of consulting documentation (if you even have any). However, the result is dependent on the expert’s availability: if their response time is slow because they are in a different timezone, on vacation, or simply have many demands on their time, the lack of information becomes a blocker for the team.

Furthermore, this expertise often remains in the developer's head, leaving with them when they change jobs.

Therefore, reliance on individual knowledge becomes problematic as teams grow or experience turnover and it can hinder efficiency.

Tribal Knowledge

Tribal knowledge is the collective wisdom within a team, informally shared through interactions and experiences. This includes unique methods, workarounds, practices, and solutions that are understood within the team but not documented.

This issue can be exacerbated by the development of an unintentionaltransactive memory system(link is external): members specialize in different domains of knowledge, and while not a single member knows everything, everyone knows who to turn to for specific information.

As teams scale, the reliance on tribal knowledge can lead to delays in onboarding new members or losses of knowledge as members depart. Effective documentation becomes crucial as it is always available, searchable, and easy to reference.

Ineffective Documentation Practices

Reading code is harder than writing code not only because everybody has their preferred approach to solving a problem, but also because developers often forget that they have two audiences: the first is the compiler and runtime and the second is the next developer who has to read or edit their code (or even the original developer returning to the code after a long time).

Indeed many developers forget that they need to communicate to humans as well as computers, and end up writing code that works but is not easily understandable.

A practical example from "Understanding Software" by C J Silverio before and after using clear variable names

The risk of encountering disorganized and messy code (especially when it comes to legacy systems) is one of the main reasons why the practice of claiming that "the code is self-documenting" is not viable.

Furthermore, no matter how clean and well-organized your code, it would fall short in capturing design decisions, trade off analysis, and system requirements, which are as important in understanding a software system as the codebase.

Lastly, a benefit of the documentation is that it caters to both technical and non-technical stakeholders, ensuring alignment cross-teams.

Inefficient Communication Mediums

When organizations grow and the software systems become more complex, one of the hardest challenges is sharing knowledge quickly and efficiently.

For that reason choosing effective communication channels, that provide persisted, accurate, and accessible institutional knowledge, becomes crucial.

Reliance on inefficient methods, such as synchronous meetings or informal Slack messages, can cause teams to waste time searching for information in disparate places, make mistakes due to outdated or incomplete information, and have to backtrack due to misunderstandings.

We all have experience juggling calendars just to schedule a stand up call or attending a meeting where someone forgets to hit record. Furthermore, meeting notes are not always transcribed, consolidated or distributed in a timely fashion and long email chains with hundreds of exchanges and multiple stakeholders, can leave out important points.

Even the most effective communication medium — visual communication — can be inefficient if the information is not current and easily accessible. For example, a system architecture diagram picture that does not reflect real-time changes can mislead rather than inform.

Go to: Pitfalls of Engineering Communication That Lead to Technical Debt - Part 2