Skip to main content
 

Great communication for software teams

The more distributed a team gets, the more important great communication becomes.

Distributed can mean many things:

  • Geographically - not in the same place
  • Temporally - either not in the same timezone or on the same schedule
  • Organizationally - the organization might have grown to a point where people aren’t organically all working with each other anymore, or areas of focus are otherwise disparate
  • Philosophically - areas of work are so different that there are entirely different mindsets, contexts, and modes of working at play

In most cases, it’s likely to be more than one of the above. For example, a team that works remotely is geographically distributed, may be temporally distributed, and depending on the size of the organization, may also be organizationally and philosophically distributed.

How do you stay on the same page with a team that has one or more of these properties?

A synchronous communication tool like Slack can be useful in some circumstances, but there’s a ceiling to the help you can get from it when people are in radically different timezones. Similarly, it’s hard to hop on a meeting to hash something out with someone who’s six hours offset from you. It’s not that you can’t talk - but you have to plan to do so.

Even without that temporal distribution, it’s interruptive to use synchronous tools. This is where philosophical and organizational distribution comes into play: they may not say so, but if you interrupt an engineer to have a quick meeting several times a day, they will be quietly plotting your demise. Their way of working requires long periods of deep focus in a way that some other roles may not. You’d better make sure those synchronous meetings are planned and predictable.

The truth is, every team is distributed, even if they’re in the same room. You can even think about temporal distribution as looking back at work that was done six months ago: you can hardly have a Slack conversation with your past self to understand what on earth you were thinking.

Luckily, we have a centuries-old method for sharing information across time and space. There are two important verbs to consider: reading and writing.

Writing is a core skill for everyone on every team. Being able to lay out your ideas, reasoning, and intention in complete sentences with empathy and depth isn’t a nice-to-have: it’s the only way to convey your thinking in an enduring way. Diagrams and illustrations can be additive, but aren’t a replacement for a well-written description. Similarly, rough notes don’t cut it: you might think they make sense in context, but months down the line, the context is stripped.

Reading is also a core skill. You can write all you want, but if that documentation is simply falling into a void, it’s useless. Active reading - the act of reading with an intention to understand and reuse the information - is a skill that every knowledge worker needs to develop.

Both of these skills must be intentionally developed as part of the culture of the team. A culture of thoughtful reading and writing as a natural part of building a product reduces dependence on interruptive, expensive synchronous communication, improves mutual understanding of the work being undertaken, and provides space for reflection on the approach before diving into execution.

As part of a software team, I believe each of these is an important written document:

  • The product spec - a concrete, human-centered description of what the product is through the lens of the real people it’s being built for, what their problems are, and why this product will be effective in solving them. This document is designed for feedback from business teams and the engineering team that will be taking on the work.
  • The engineering spec - a description of how the engineer intends to go about building it. This includes the technical goals, but also the non-goals: what’s intentionally being left out of the build. This document is designed for feedback from other engineers and the product team.
  • Stories - concrete descriptions of atomic pieces of work, derived from the product spec, with well-defined acceptance criteria. These stories may embed illustrations or designs, but an illustration or design is not a story. Stories are usually wrapped up in an epic, a kind of meta-story that describes the arc of the work.
  • Tasks - descriptions of the individual engineering tasks involved in building a story.

Each of these is designed for an audience in order to solicit feedback, which will then be used to improve the description; more feedback is sought, and so on. Iterative loops of feedback, testing, and improvement are the core pattern of software development.

Not everyone is a natural writer, or will be a native speaker of the written language of the team. Reading lots of documents with different structures also undeniably carries a cognitive load. Templates can help here: pre-defined headings and document structures that allow authors to fill in the blanks if they need to, and allow readers to more quickly find the information they’re seeking. In teams I run, I always make sure there are templates and examples to choose from.

In a tiny team, you can often get around having this level of description: you talk about it, you do the work, you check in with each other organically. But as the team becomes more distributed, this becomes less possible; context is lost and inefficiencies grow between the gaps. You can’t have everyone checking in with everyone all the time. Nobody would get anything done; meetings with lots of people are expensive; synchronous meetings tend to favor extroverts.

Like all elements of team culture, it’s important to intentionally create it early: the culture you create at the beginning will inform what happens when you grow. Because this inflection point is an inevitability in a growing team, setting a culture of strong asynchronous communication and documentation early will prevent problems later on. Like all elements of culture, that means you need to intentionally hire for it, intentionally train for it, and intentionally lead by example.

 

Photo by Lagos Techie on Unsplash

· Posts · Share this post