Although we mostly split the work on my project so that there aren't too many dependencies between the teams in Chicago and Pune, there have still been some times when we've designed major parts of the code base in Pune and have needed to communicate that to our Chicago colleagues.

I've never seen this situation so it's been interesting to see which approaches work in trying to do this effectively and allowing the people in the other location to have input as well.

Explanation on specific email threads

While it's useful to communicate the approach being taken by email we've found that it makes more sense to have a specific email thread for that conversation rather than tagging it onto something else.

It's surprisingly easy for emails to get lost amongst the hundreds of others that people receive each day but at least if the important messages are all under an email with a clear title then it's much easier to deal with.

While discussing this with Saager, he suggested that an effective approach he's used previously is to include details of design decisions taken in commit messages and then point people towards those particular commits.

Of course however skilful we may be in communicating via email it does help to talk on a conference call as well – that medium seems to work better for explaining the reasoning behind decisions, especially if there's a disagreement in the approach.

Commit early

As much as we can explain design decisions in emails or conference calls it's still not as useful for people as seeing the actual code which is something we didn't totally appreciate until recently.

We're now trying to ensure that we check in more incrementally when making big design changes.

This should help to tighten the feedback loop and ensure that we get the benefit of the design skills of people onshore as well as offshore.

Something which I initially considered as a disadvantage with checking in incrementally is that you will most likely get suggestions/criticism about what you've done even if you had already planned to address some of those areas anyway.

As a colleague correctly pointed out, the intention is generally good and it's not the end of the world if someone suggests something you could have done better anyway.

In summary

These types of things seem obvious looking back at them now but I guess it isn't so obvious to me because you never have to think about them at all when anyone interested in the code is sitting in the same room as you as it's been for me when working onshore.

I'd be interested to hear any other approaches that have worked well for others working in a distributed fashion.

From http://www.markhneedham.com/blog/2010/11/10/distributed-agile-communicating-big-design-decisions/