Pitfalls of Engineering Communication That Lead to Technical Debt - Part 1
May 28, 2024

Thomas Johnson
Multiplayer

Over many years of research, 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: 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

Thomas Johnson is Co-Founder and CTO at Multiplayer
Share this

Industry News

June 20, 2024

Oracle announced new application development capabilities to enable developers to rapidly build and deploy applications on Oracle Cloud Infrastructure (OCI).

June 20, 2024

SUSE® announced new capabilities across its Linux, cloud native, and edge portfolio of enterprise infrastructure solutions to help unlock the infinite potential of open source in enterprises.

June 20, 2024

Redgate Software announced the acquisition of DB-Engines, an independent source of objective data in the database management systems market.

June 18, 2024

Parasoft has achieved "Awardable" status through the Chief Digital and Artificial Intelligence Office's (CDAO) Tradewinds Solutions Marketplace.

June 18, 2024

SmartBear launched two innovations that fundamentally change how both API and functional tests are performed, integrating SmartBear HaloAI, trusted AI-driven technology, and marking a significant step forward in the company's AI strategy.

June 18, 2024

Datadog announced the general availability of Datadog App Builder, a low-code development tool that helps teams rapidly create self-service applications and integrate them securely into their monitoring stacks.

June 17, 2024

Netlify announced a new Adobe Experience Manager integration to ease the transition from legacy web architecture to composable architecture.

June 17, 2024

Gearset announced a suite of new features to expand the capabilities of its comprehensive Salesforce DevOps platform.

June 17, 2024

Cequence announced a new partnership with Singularity Tech, an Australia-based professional services company with expertise in APIs and DevOps.

June 13, 2024

Elastic announced a partner integration package with LangChain that will simplify the import of vector database and retrieval capabilities of Elasticsearch into LangChain applications.

June 13, 2024

Fastly announced the launch of Fastly AI Accelerator, the company’s first AI solution designed to create a better experience for developers by helping improve performance and reduce costs across the use of similar prompts for large language models (LLM) apps.

June 13, 2024

Shreds.AI, ant AI capable of generating complex, business-grade software from simple descriptions in record time, announced its formal beta launch.

June 12, 2024

GitLab announced the public beta of expanded integrations with Google Cloud that will help developers work more effectively, quickly, and productively.

June 12, 2024

Pulumi announced Pulumi Copilot, AI for general cloud infrastructure management.

June 12, 2024

Harness completed the acquisition of Split Software, a feature management and experimentation provider, effective June 11, 2024.