HomeArticlesFinding Communication Hook Points

Finding Communication Hook Points

Want to receive these updates in your inbox? Sign up for my mailing list using the form on the right. (or below if you're reading this on your phone)

When building software, it's common to discuss necessary vs. unnecessary complexity in your architecture. Unnecessary complexity usually comes in the form of abstractions that are rarely used and take more effort to maintain than the lower-level code that they replace.

Necessary complexity, on the other hand, is exactly what it sounds like. It's the complexity that arises from adding components to your architecture which solve real problems. There is some cost involved in understanding the role of the abstraction and how to use it. Once you've cleared that hurdle though, this type of complexity is worthwhile because it lowers maintenance costs, increases reliability, or streamlines commonly performed tasks. One thing that separates a good developer from a mediocre developer is recognizing the cost of added complexity, and making an accurate assessment of whether that cost will pay off.

The same cost-benefit thinking has to be applied when plotting team communication requirements. In my previous post I repeatedly referred to communication protocols. That word was chosen intentionally. To keep communication costs low, the steps should be well defined, routinized, and clearly understood by all developers. To do this, look for hook points in your process where you can build in templated, automated prompts for your developers to communicate with the team, so they quickly just become steps in the process that your devs don't need to think about or remember to do.

A good example of this is Pull Request Templates. If your team follows a PR-based code review process on Github or most any other Git hosting service, you can create a template file for the pull request description. When developers create a pull request for a feature, the description field of the PR will be populated with this template. All a developer has to do is fill in the blanks. Here's one I use, which incorporates a checklist of ancillary tasks and specific correspondence.

The reason this works so well is that the developer doesn't have to remember to do anything. We've hooked into a step that every developer will take in the course of shipping a feature, using that hook as a reminder to communicate all of the items that need to be communicated. By making these steps into rote repetition, you gain a few benefits.

First off, developers are more likely to actually provide the requested information if it is presented in a fill-in-the-blank style. This style makes it faster for them to complete, and it makes it really obvious if something is omitted. Keeping the format consistent and prescriptive means the developers get faster at generating them over time, communicating more effectively in less time.

Another benefit of using hook points in your process is that you can define canonical locations for certain types of information. For instance, with this template you can be assured that any special notes that need to be taken care of at deployment will be noted in the work ticket. With a few hours of coding, any semi-competent developer can then write a script to extract all of the deployment notes from any cards that are waiting to be deployed. Now your DevOps team (which may just be your dev team) can quickly generate a comprehensive list of deployment notes that need to be addressed in addition to the normal release protocol (think database migrations, new environment variables, etc), leading to fewer surprises during or after deployment.

Nobody likes surprises during a deployment.

Building your communication protocols around hook points in your process is analogous to building an application on a well-documented and well-tested API. You know exactly when these steps will occur, and you can clearly define the events and behaviors that will occur as a result. Other hook points could be your morning standup or starting a new work item.

What are some other points you can hook into in your process to prompt proactive developer communication?

Ben Wilhelm

Is your dev team working hard but not shipping? I can help.

I send a few emails per week with tips and ideas to help your team stop thrashing and start shipping reliable code consistently.
"What we got from Ben was more than just expertise: it was expertise plus organized thinking, clear communication, good humor, and an obviously habitual willingness to listen before advising. We recommend him without reservation, and look forward to the next time we work with him ourselves."