Clear Communication in Software Development Starts with Semantics

There’s an oft-repeated adage that the hardest thing in programming is naming things. As it turns out, that naming issue extends to everything around the product too.

Communication’s role as a critical feature of the web application process has come up in a number of our articles, but when does it start? Most take communication to mean that we’ll be talking about the project’s status a lot, but before all that, you have to address semantics.

Organizations that need developers and the software they create are a mashup of domain expertise. Each brings special acronyms, foundational concepts, and a wholly separate idea of what words mean. The rub: Everyone loses sight of how steeped into their domain they’ve become, making one person’s base camp another person’s mountain to climb.

At best, you’re building features amidst confusion and misconceptions that’ll reveal themselves down the road. At worst, you’ll alienate team members who may hold the most valuable insights.

To avoid those outcomes, let’s throw a spotlight on the sources of semantic gaps, their impacts, and what can be done to build a bridge.

Avoiding Developers’ Tech Speak

Rather than kick things off by pointing fingers, I’ll hold up a mirror — tech speak is a semantic nightmare, and we’re well aware of it. Some of my favorites from the last decade include:

• kill unicorn
• stabby lambdas
• strangler pattern
• client-side rehydration

All sound pretty nonsensical out of context. Worse, many people have experienced that nonsense delivered with an antagonistic bedside manner.

Picture a doctor visit. In the middle of diagnosing your concern, how would you react if the doctor leaned into the deep cuts of medical jargon and assorted Latin phrases? What if they doubled down and acted put out (or smugly superior) when asked for the simple version? You’d likely be on the lookout for a new doctor, and the same should ring true with developers who treat their domain as a throne. Communication requires a middle ground, and tech speak only serves to estrange stakeholders, who are often already anxious about the tech mythos, and non-technical members of the developer’s own team.

One final point to keep this short of a rant: Addressing a diverse team with industry jargon and acronyms isn’t endearing to the other developers present. It’s the programming equivalent of pulling a guitar out and breaking into Wonderwall.

At any rate, technology comes with language of its own, and that’s the first gap to hop.

Unraveling Your Product’s Domain

With that out of the way, now we’ll do a bit of finger pointing. Or some light gesturing, at least.

The hardest part of knowing something is teaching it to someone else, and that’s your primary role as resident expert when a new project kicks off. Custom software implies that there’s something unique about what’s being built, and that secret sauce needs to be communicated to the team expressing it through code.

Strategists, developers, designers, and all the specializations in between will seek a crash course in the problem space and an explanation for all those acronyms. The implementation team aims to match your domain’s needs to the accepted paradigms and patterns that make an application tick, so the holders of intellectual property will quickly need to take up the mantle of educator.

At the very least, expect to be available for questioning as the project team delves deeper.

The Cost of Semantic Gaps

Missing the mark on meaning from either side affects everyone, end to end. Let’s take a look at the primary costs from each side of the equation.

Stifling the Source of Ideas

The most valuable application ideas often come from non-technical contributors. Folks with deep expertise that can be scaled and automated, but lack the know-how when it comes to software. That missing development knowledge can feel like an intimidating gap — or full-blown chasm. If they don’t feel heard, aren’t asked about their experience, or are reluctant to share in any way, it’s a huge blow to the project’s potential.

Even if they aren’t the primary stakeholders, we need to hear from the individuals who’ll be using the platform everyday. Building a product that doesn’t meet their needs or leverage their know-how leaves value on the table.

Non-Native Speakers

On the opposite end, implementation relies on just how well the development team understands your distinct take on the domain. It’s like the difference between Google Translate and a native speaker: the product will come close, but may lack context, nuance, or an altogether better approach.

More directly, if each team has a different understanding of the vision, the codebase may quickly run up against issues with scale, performance, and the ability to iterate. It’ll lack the right affordances for the future.

Making Everyone a Contributor

Antagonistic developers, explanations that miss the mark, and second thoughts about sharing: How do we actually set all of this up for success? Here’s the starter pack for semantic success.

Leadership Sets the Example

Behavior is modeled from the top, and a leader willing to pause a discussion (or be interrupted) for clarification goes a long way. Demonstrate knowledge share in a way that’s worth mimicking.

Lean on a Moderator

Strong personalities shine through in group settings, as does a deference to ranking members. An equally driven moderator helps move the spotlight around and set up avenues of conversation for success.

Take dot voting, a popular means of prioritizing project objectives. Left alone, a persuasive individual can skew the exercise by going first or campaigning for their favorites. When that sort of situation is identified, a moderator can mitigate their influence by dictating order or turning to a voting method that’s purely digital.

Be a Willing Teacher

Experts teaming up with other experts (yep, software is pretty much The Avengers) have to be prepared to explain, re-explain, and patiently teach the finer points of their specialization. Treating teaching as a hardship keeps folks from seeking it out. And, if it isn’t taught, it’s a safe bet that the implementation will miss the mark.

Start With a Dictionary

The longer an organization exists, the longer its list of internal acronyms grows.

Consider including a dictionary within production documentation to keep track of non-obvious terms for team members that cycle in and out.

Translate When Necessary

As a group, conversations should happen in a shared language. There are plenty of times, though, where decisions hit a point where it’s okay to translate it back into something more proprietary.

Feedback like this page loads slowly is effective within a team update, but could stand additional detail when it makes its way into a development ticket.

Starting Software With Semantics

If there’s one thing worth taking away from the content we produce, it’s that communication decides the outcome of an application. It begins alongside the very first project conversation: Are we speaking the same language? How do we get there?

Once teams have found a common base camp, efforts shift towards maintaining that mutual understanding — collectively making sure that we’re climbing the same mountain, together.

We’re all experts in different things for a reason, and bridging the uncertainty between specializations is the first step in making sure everything will work out.