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 —such as 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. An inadequate communication framework 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 and miscommunication.

This lack of alignment and confusion inevitably results in technical debt, manifesting as subpar architectural choices, inconsistent solutions, missing documentation, complex dependencies, and other challenges.

Regardless of whether an engineering team is colocated, remote, or hybrid (such as an organization spread across multiple corporate offices), 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 project requirements, the system design vision, 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, inconsistent 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.

(A) 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 solutions, validating system designs, discussing problems with colleagues, and hypothesizing potential issues.

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 in the tech industry—approximately 13% annually, with developers often changing jobs every 1 to 2 years.

(B) 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 feature development: How many sources must you consult to fully understand the implications of your changes and avoid breaking code or adding technical debt? In discussions with several engineering teams, some reported needing to access up to ten different tools—ranging from GDocs, Jira, Confluence, Notion, Slack, GitHub, VScode, Linear, and diagramming tools—before beginning to code.

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 persistent, accurate, and accessible institutional knowledge. They also lack real-time multi-user editing capabilities (e.g. most diagramming tools), 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 building 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

Software engineering is inherently social and effective knowledge transfer and documentation are crucial for mitigating technical debt and enhancing team performance.

Here are three strategies to mitigate the most common communication pitfalls:

1. Internal Processes: Establish consistent practices for discussing and documenting technical decisions, such as engaging in continuous system design reviews. This approach helps preserve institutional knowledge across all aspects of the system and teams, contributing to the longevity and stability of projects while breaking the cycle of reliance on tacit and tribal knowledge.
2. Centralized Knowledge Base: Consolidate all critical assets in a single, easily accessible location. A unified knowledge base streamlines workflows, reduces context switching, and accelerates decision-making, ensuring that all team members have immediate access to the information they need.
3. Automated Tools: Leverage tools that automatically capture and store institutional knowledge, reducing the burden of manual updates. Choose tools that support visual, real-time, and asynchronous collaboration to meet diverse team schedules and facilitate effective communication, while also enabling necessary synchronous interactions.

Accurate documentation practices can significantly impact an organization. In large organizations where multiple teams work on various components of a distributed system, a well-documented architecture ensures consistency, reduces the risk of errors, and supports compliance with industry standards, regulatory requirements, and best practices.

---

Addressing these challenges requires a deliberate strategy to capture and formalize knowledge. Investing time in documenting team and system knowledge pays dividends in faster onboarding, quicker feature implementations, and safer system refactoring.

Multiplayer enables you to visualize, design, and develop your distributed software using a visual and collaborative tool. With all necessary information—from system architecture and components to APIs, environments, and decision records—readily available on an easy-to-navigate, always up-to-date platform, you can truly empower your team.

Sign up for free and see for yourself! 😉