== Notes to self ==
Not gold alone brought us hither

Effective Team Communication in Software Development

Irrespective of your role in Software Development (software development engineer, product manager, quality engineer, engineering manager, director or above), all the tools you use to get the job done can be broadly categorized as:

  • Tools for communication and collaboration
  • Tools for software development and testing
  • Tools for software operations

In this article I will discuss the first in that list: Tools for communication and collaboration. A software development team’s effectiveness and long-term success hinges upon how they communicate and collaborate within the team as well as with external stakeholders. Understanding the hierarchy of communication and developing a knack for choosing the right level of communication has long term benefits. This is a learnable skill, but like any other soft skill, it requires ongoing calibration in the team. You need a few people who care about this and can set the tone for everyone else.

The hierarchy of communication and collaboration has the following layers:

  1. Team Wiki
  2. Team Blog
  3. Documents
  4. Issue Tracker
  5. Team Chat
  6. Personal / Group chat
  7. Good old face-to-face interaction

Every time you communicate or collaborate with others, you need to choose an appropriate tool from this hierarchy for maximum impact. This hierarchy has the most durable medium at the top, where discoverability and shareability is also high; all of which reduce when you pick tools lower down in the hierarchy. The signal to noise ratio is also high at the top and falls as you go down the hierarchy. For e.g., any information shared in a face-to-face conversation is least durable, discoverable, or shareable. The only short-term benefits of sharing information in the lower layers are high speed and less formality, which is indispensable in day-to-day work but should not be applied to every piece of information. (By tools I mean product type. For e.g., your wiki could be Confluence, GitHub wiki, or something else; Documents could be Google Docs, Office 365 Word, or something else; and so on.)

Let us now discuss each layer:

1. Team Wiki: Think of a good wiki as a garden that grows with the product and with the team. It is the team’s collective brain. It is home to the ever-growing information about what the product is, how it works, links to useful resources, known issues, roadmaps, release history, team member details, processes, etc. It should be possible for you to just grant access to the wiki and they should be able to find all the information they need. For e.g., anyone in your team should be able to figure out how to set up their development environment, where to download the product and how to install and run it, learn about the team’s software development processes and practices, how to start taking part in team rituals etc. The wiki should be open for contribution from all team members, but with some oversight from the senior members to keep entropy at bay. Maintaining the wiki is an ongoing process that should become second nature to the team. Just like a garden, it needs constant caring, pruning, weeding, and nourishing.

2. Team Blog: This is best for sharing narratives which are snapshots in time. Information you publish on the team blog is not expected to change with time. Information that needs to be updated over time belongs to the wiki. Blogs are for things like release announcements, process change announcements, welcoming a new team member, saying goodbye to a departing team member, announcing promotions or role changes, etc. Blogs are searchable and you can read posts from the past to gain perspective of how things evolved over time. (The conventional way of broadcasting announcements by email should be replaced by blog posts. Emails have a major drawback: information in emails is trapped in people’s inboxes. It cannot be discovered by someone who did not receive that email, and they are forever locked out of that piece of information. For example, when you join a company, you do not have access to emails that were sent prior. If you must send an email, first publish your announcement as a blog post and then email the link of that post to your target audience.)

3. Documents: These are best suited for collaborative writing or for receiving feedback on your writing. Use online documents for sharing and reviewing product requirements, system design, technical roadmaps etc. Once the review comments are addressed and the content is finalized, you can either move this to wiki or blog depending on the type of information. If your team has a good reason to archive these documents for later reference (instead of publishing this information in a wiki or a blog), then make sure the documents are stored in a location that the entire team can access, and they are well organized in a folder hierarchy.

4. Issue Tracker: This is where you submit and track Change Requests (we will call them CRs). Most modern issue trackers are also project management tools which aid project planning, release management and more. In this discussion, we will focus on information exchange facilitated by issue trackers. Each CR tells a story, which starts with the description of a new feature, enhancement, or a bug, and as the team makes progress on this CR, it serves as a log of milestones on the way to accomplishing the objective of that CR. Some teams use issue trackers only for process compliance, and the real conversations happen somewhere else – either on chat or even face-to-face. The downside of this approach is that your “process” is now a burden and only serves as a paper trail solely for the sake of compliance; you are not using the tool to improve collaboration. A well written CR allows you to assign or transfer it (at any stage) to someone without the overhead of having to explain everything to them. The CR should be up to date and self-explanatory.

5. Team Chat: This is where the team congregates and communicates asynchronously. Use topical channels to streamline conversations thereby allowing people to selectively tune into relevant conversations. Avoid posting messages in a “general” channel (unless, of course, it is a broad announcement) or else your team chat will become a noisy bazar where focused dialogs are no longer possible. Do not expect people to always respond promptly as it will kill their ability to focus on tasks; it is a tool for asynchronous communication! Once you start a conversation and it reaches a logical conclusion (either a decision is made, or a new plan is agreed upon etc.), this information should land in a better place. It could be a wiki, issue tracker or whatever is right for the topic. Best thing about team chat: it is inclusionary since every team member is tuned in, including the quiet ones.

6. Personal / Group chat: This is to send direct messages to individuals or to a group of selected people. Use this only when you are discussing something that would be considered too noisy for team chat channels. The reason not to use group chats for work related topics is because it is exclusionary. Such conversations reduce your team’s shared understanding of what is going on since it excludes some or many of your team members from the discussion.

7. Good old face-to-face interaction: This is the bottom rung of the hierarchy and is suitable for getting to know each other, for 1x1s, and for relationship building. While all of this can be done with video conferencing, occasional in-person interactions help build trust and relationship. However, in-person interaction is not necessary for day-to-day work. Remember, effective communication requires us to feed the collective brain. If essential information is exchanged via in-person conversations without surfacing it in any of the other layers discussed above, you are starving the collective brain.

That is the hierarchy of communication. Since it involves a lot of writing, here’s a quick note about writing in general:

  • Keep it simple across the hierarchy
  • Structure and categorize information to make it easier to find, even for new members
  • People will initially confuse the hierarchy and that is ok; it is part of learning
  • When adding information anywhere in the hierarchy, ensure there is sufficient context and cross referencing
  • Pay attention to spelling, grammar, and formatting; because typos, bad grammar, and poor formatting reduce readability and are distracting

In conclusion, every time you communicate or collaborate with your team members, pick the right tool. By default, it is easy and tempting to stay in the lower layers of the hierarchy because most people feel safe there, since they do not need to worry about making mistakes, communication feels natural and informal etc. It is a trap! Always strive to continuously refine valuable information and move it up the hierarchy to the right level where it belongs.

What I have outlined above is what has worked for my teams; you may have a system that works better, and if so, please share in the comments (or create your own post and share the link in comments).

PS: Thank you Deepesh and Ravitheja for reading the draft, providing valuable input, and for pointing out errors. Any remaining errors in this post are mine.

PPS: This article first appeared on LinkedIn here.