Tackling technical debt through strategic communication

In engineering teams where communication is challenging, software development often becomes a balancing act between HIPPO (”Highest Paid Person’s Opinion" syndrome) and design by committee. Decisions may be dominated by a single senior individual, or muddled by a lack of clear vision as the team strives to satisfy everyone's requirements, typically resulting in a weaker product.

In general, teams are such complex systems that there are many dynamics. For example: groupthink, the tyranny of small decisions, the bandwagon effect, etc. All of which can significantly impact communication and lead to subpar decisions.

Communication and collaboration are crucial in determining team success. Indeed, several studies have found they are more reliable predictors of success than any of the other qualities we usually associate with great teams: individual intelligence, personality traits, personal motivation and satisfaction, or a feeling of cohesion and camaraderie.

However, crafting the right communication strategy can be challenging. Too much information can overwhelm team members, causing key details to be lost amidst the noise, or distracting from core tasks. Inadequate communication can leave team members without sufficient context to make informed decisions, forcing them to depend excessively on others for information, and generally leading to misunderstandings.

This lack of alignment and confusion inevitably results in technical debt, manifesting as complex technical issues, hard-to-reproduce bugs, subpar architectural choices, inconsistent solutions, complex dependencies, and other challenges.

Regardless of whether an engineering team is colocated, remote, or hybrid, they face the same inherent communication pitfalls. This article explores the most common pitfalls that lead to communication issues, along with strategies to mitigate them.

Common communication pitfalls in engineering teams

(1) Different Mental Models

The term “Mental Models” was introduced in 1943 by Kenneth Craik, who suggested that our minds build "small-scale models" of reality to anticipate events. These mental models are abstractions created by our brains to help us understand the world, influencing our behavior and problem-solving approaches (akin to having personal algorithm in our minds).

Given that each person has different mental models, experiences, skills, frames of reference, etc. we naturally process information and implement solutions differently. Therefore, it’s not surprising that presenting two engineers with the same problem will likely yield two distinct solutions. Moreover, if they collaborated, they would help each other break out of personal biases and expose innovative approaches, resulting in a third unique solution.

In engineering teams, a common pitfall is the assumption that all members share the same understanding of a bug, feature requirements, system design, or the implementation plan.

Without fostering alignment and engaging in transparent, proactive communication, it’s easy for individuals and teams to inadvertently work in silos.

This lack of coordinated understanding can lead to misunderstandings, long back-and-forth to fully understand an issue, delayed solutions, and ultimately, the accumulation of technical debt and the need for rework.

(2) Undocumented Knowledge: Tacit and Tribal

Informal, undocumented knowledge can take the form of tacit or tribal knowledge.

Tacit Knowledge

“Really good developers do 90% or more of the work before they ever touch the keyboard; really understanding the requirements and devising an appropriate solution.”

- Tim Ottinger

Software development is a highly skilled knowledge job that involves a variety of complex and creative tasks beyond just writing code. Indeed, developers spend considerable time collecting requirements, researching issues, discussing problems with colleagues, and hypothesizing potential solutions.

And while writing code is a self-documenting activity (to a certain degree), all these other tasks are seldom documented, and instead contribute to an individual’s tacit knowledge.

This type of knowledge encompasses personal wisdom, experience, insight, and intuition that is often difficult to articulate and share through traditional means.

Think about the insights a senior developer acquires after years of working with a specific legacy system. They develop a keen intuition for identifying root causes of issues or optimizing algorithms for particular scenarios. Their deep understanding of the codebase and its interdependencies enables them to instinctively navigate and evolve the system effectively.

However, transferring tacit knowledge poses challenges particularly in larger teams. Senior developers often are the default go-to people for questions about a certain topics and they becoming inundated with questions from junior team members. Junior engineers, in turn, face delays in their work due to the unavailability of crucial insights they can’t obtain until the senior developer has time for them.

Relying on developers to share their tacit knowledge is a recipe for loosing institutional knowledge, especially given the high turnover rates (and recent layoffs) in the tech industry.

Tribal Knowledge

Tribal knowledge is similar to tacit knowledge, however it’s the collective wisdom accumulated within a team that often goes undocumented. It includes personal stories, learning experiences, and insights gained through mentorship and on-the-job training. This knowledge is passed from one engineer to another and is assumed factual despite often lacking concrete data or analysis to verify its accuracy.

In practice, tribal knowledge manifests as unique methods, workarounds, practices, and solutions known within the team but opaque to newcomers. Although it presents less risk than tacit knowledge (since it does not rely on a single individual) it still leads to challenges such as delayed onboarding and difficulty in standardizing practices across teams.

(3) Ineffective Documentation Practices

“The reason that they [programmers] think the old code is a mess is because of a cardinal, fundamental law of programming: It’s harder to read code than to write it.”
- Joel Spolsky

Over the years, engineering teams have experimented with various documentation strategies, achieving mixed levels of success. Some have encouraged developers to write documentation themselves, others have employed dedicated technical writers, and still others have integrated documentation tasks directly into development sprints.

However, this perspective overlooks two critical truths:

1. Reading vs. Writing code: Reading code is inherently more challenging than writing it, not just because each programmer has their unique problem-solving approach, but also because most projects involve brownfield or legacy systems. These are often extensive code sets touched by many developers over time, complicating comprehension.
2. Beyond the code: Code alone often fails to capture essential elements such as design rationales, trade-off analyses, and system requirements. Understanding a software architecture thoroughly requires more than just the codebase; it demands comprehensive documentation that addresses all of these aspects.

Effective documentation practices must consider the entire software system and cater to all stakeholders, including both technical and non-technical personnel.

(4) Fragmentation of Knowledge

Fragmentation of knowledge and communication tools is consistently highlighted as one of the top recurring problems affecting developer productivity.

Consider the typical workflow during debugging: How many resources, tools and teams must you consult to fully understand the issue?
In discussions with several engineering teams, some reported needing to access up to ten different tools, ranging from support help desk, session replay tools, APM dashboards, error management tools ... you're hopping between Zendesk, Jira, Fullstory, Datadog, Sentry, Slack, GitHub, etc. And at the end, you might still need to schedule a "sync meeting".

The need to constantly switch context can be immensely time-consuming and increases the risk of overlooking crucial information. Moreover, there are not many tools that effectively support real-time, full-stack visibility into a specific system behavior or bug. They also lack collaborative editing capabilities, hindering asynchronous collaboration and communication.

It’s akin to assembling IKEA furniture in one room but only being able to communicate in another. Imagine the waste of time and frustration of having to go into a different room, wait for your colleague to join, exchange the necessary information (”Pass the screwdriver”), and then back to the original room, recover from context switching, and then continue with your half-assembled project.

Now, extend this analogy to the complexities of debugging a distributed system with hundreds of components across remote teams. The cognitive load required to reconcile work and communication is significantly magnified.

In summary, many teams struggle with an over reliance on too many tools, some of which lack critical functionality necessary for effective team collaboration and information coherence.

Strategies to mitigate communication issues

Addressing these communication pitfalls requires intentional strategies that reduce friction, preserve knowledge, and create shared understanding across your engineering team.

Reduce tool fragmentation strategically: Audit your team's tooling and identify where context switching causes the most pain. You don't need to consolidate everything into a single tool, but focus on reducing fragmentation in your most frequent workflows. For debugging, this might mean choosing tools that provide comprehensive visibility rather than cobbling together partial views from multiple sources.

Create shared artifacts during investigation: When debugging issues, particularly complex distributed system problems, create artifacts that capture the full context: what you observed, what you tested, and what you learned. This transforms individual investigation into institutional knowledge and helps future engineers facing similar issues.

Tools that automatically capture end-to-end context (from frontend user actions through backend traces and logs) can significantly reduce the communication overhead of understanding what actually happened. When the full story of a bug is captured in one place rather than scattered across session replays, APM dashboards, and support tickets, teams spend less time reconstructing context and more time solving problems. This kind of consolidated visibility not only accelerates debugging but also creates a natural artifact for cross-team communication, whether that's engineering explaining an issue to support, or senior developers helping junior teammates understand complex system behavior.

Encourage asynchronous-first communication: Not every discussion needs a meeting. Favor visual, asynchronous communication for most coordination, reserving synchronous time for truly collaborative work like pair programming or complex design discussions.

Build feedback loops into your process: Regularly retrospect on communication breakdowns. When misalignments happen, don't just fix the immediate issue, discuss as a team what communication gap or workflow inefficiency led to the problem and how to prevent similar issues.

Effective communication in engineering teams isn't about perfection, it's about creating workflows and habits that reduce the friction of staying aligned. By addressing these common pitfalls with intentional strategies, teams can significantly reduce the technical debt that stems from misunderstanding and misalignment, ultimately building better software.