Architecture and Communication

My post today is going to talk about how software architecture can be a vehicle of communication.

What is Architecture?

Wikipedia defines architecture as the structure or structures of system, which comprise software components, the relationships among those components, and the relationships between them.

When software engineers think architecture, they primarily think of architecture and documentation and diagrams of the above-mentioned structure. And the popular “architecture” sites support such notions.

For example, Wikipedia lists the Common language infrastructure architecture as this:

The documentation suggests that all the code of the different languages get compiled to Common Intermediate Language. However, it does not say some significant things: Does the compilation support the full-fledged language or does it apply restrictions on the languages for compilation? Can the languages communicate with one another? And most importantly, what quality attributes does this architecture support, and why?

Any such diagram can raise these questions, and it is important that the development team is knowledgeable about the answers. Without architectural knowledge, the team may not have a good big picture view of the system.

This "lack of big-picture view" happens in both small and big companies. Roni Burd, a program manager at Microsoft, discovered this issue with his Bing development team. He had to take action to raise the architectural awareness of the team. I have noticed this also at my new job, where the software is too large to comprehend without proper architectural perspectives. Without good architecture documents, the team members each get familiar with parts of the system, but no one can really talk about the system as a whole.

It is the architect's job to ensure that the development team is adequately knowledgeable about the answers to these questions. S/he can share this knowledge through documentation or architecture workshops or through any other means.

We used the following activities in Spring and Summer to raise architectural awareness:

ACDM architecture reviews:

We conducted architecture reviews throughout Spring. In these reviews, the architect would present a partitioning of the system, and explain the rationale for that partitioning. Then the team would raise and record issues with that partitioning.

What we could have done better:

We should have been more upfront about giving feedback on architecture. We all had different ideas and impressions on the architecture, and we could have done a better job at harmonizing those differences. We could not relate how the pictures and diagrams of the architecture related to the actual product. If we implemented parts of the application, that would have given us a concrete mental model of how the architecture and the actual software were connected. With that mental model, we could have been better at communicating our differences of opinion about the architecture.

Architectural documentation:

Architecture documentation was our key way to communicate in Spring and Summer. These were up-to-date diagrams of the system, with design rationale relating them to the quality attributes.

What we could have done better:

Since we were implementing the product in summer, we could have improved architectural communication by printing out the architectural diagrams and posting them in the cubicle. This would have allowed the team to question and verify the architecture as they were implementing the system.

Topic of the week:

We did have some verification of the architecture at our 'topic of the week' sessions. 'Topic of the week' was our way of addressing misconceptions. Each week, at the status meetings, we budgeted some time to talk about a topic that we needed to communicate across the team.

At the architecture sessions, we addressed the following questions: how the architecture decomposition related to the implementation, and how were the quality attributes supported.

What we could have done better:
We could have addressed more architectural topics. There were questions on how did our package structure relate to our static architecture, and why were packages decomposed the way they were. These could have been better addressed early in the project to clarify the responsibilities of each package. That would have reduced some architectural refactoring work.

What!? When’s the decision made?

Making a decision in a team is not easy, especially working in a peer group. MSE studio teams are peer groups. Although there is a team lead in the team, it doesn’t mean he or she is superior to other team members. So, while working in this kind of environment, one big question is “Who gets to make the decision?”

A Story

I remember the first conflict in the Square Root team was happened in the first semester. One day, after the class which was talking about choosing a process for a project, our team was excitingly discussing about what process we are going to use in our cubicle. Everyone was saying his opinion about what processes we should use for each semester. I remember I stood there and kept questioning “Why? Why we should use this process instead of that? Do you have any analysis to show that this process will work for our project?” However, we spent a lot of time on the discussion and we didn’t make any concrete decision. 

Sometimes it was just so difficult to let everyone in the team knows:

When to send out meeting agendas?

When to input tasks time on the sharepoint?

What data we are going to track for the estimation?

How we do planning?

Who should take the responsibility of communicating with the client?

This kind of team consensus problems happened only in a team of five. Not to mention what will happen in a larger team.

Finally, we learned to use “Proposal” to help the team communicate more effectively and to drive the team making defensible decision. 

What’s inside a proposal?

First, we wrote about the objective of making a decision. This sound trivial, but sometimes people really would forget “why they are doing this.” 

Second, the approach of the process we are going to follow. Any detail procedure of how we do things would be recorded here. 

The last but not the least – we also wrote down what metrics and data we wanted to get from this process. This is for future analysis on this process.

How does “proposal” change us?

After we used the proposal approach to make decision, the team started to create a lot more proposals than we thought! For example, we have meeting proposal, process proposal, planning proposal, tracking proposal, and even a proposal for proposals!! 

We became very clear that according to different roles who is responsible for making what decision. We spent less time on quarrelling about any decision we need to make. However, team member would review a proposal and provide very specific suggestions.

Later on, we even invent a proposal survey mechanism to use quantitative data to prove how well the proposals are.

Writing a proposal is never a fun thing, but this is one of the approaches that keep the team align and hold the team together!

Avoid Project Assumptions

Assumptions are the root of all evil on a project.

Why wasn’t the branch release made today?
The quality assurance manager assumed someone else was going to do it.

Why is this code so sloppy? It’s barely readable!
The lead developer assumed that wasn’t important.

Why didn’t anyone mention this problem earlier?
The team lead assumed folks would raise concerns before they became problems.

Why are we using this communication mechanism between the client and the server?
The architect assumed the modifiability quality attribute was not important.

Why was I the last to hear about the new quality assurance process?
The process manager assumed someone else would let you know.


The fastest way to project failure is to make the wrong assumptions. At the beginning of any project, especially when there’s a brand new team involved, there are going to be assumptions. People come with biases – judgment is one of the things humans are really good at. The more assumptions you can avoid as a team, the better off you’ll be. Write down your thoughts, talk about your history and experience with everyone on the team, write down the decisions you’ve made throughout the project, and record the justifications you used to make those decisions. But whatever you do, don’t assume.

Are you indecisive? If so, play a game!

Decisions! Decisions!! Decisions!!! They are key ingredients in the colorful life of any engineer (not just for us, the reclusive software hermits!). No longer can we secure sanctuary at the confines of our desk, hoping to have our decisions deferred indefinitely or delegated to some unwilling soul. The conclusions that we arrive at often have far reaching consequences, some of which we can barely fathom. Wouldn't it then, be wise to employ the collective wisdom of our peers to arrive at conclusions that have their benediction? But wait, does that mean more boring meetings - constructs devised to drain the energy and enthusiasm of its participating members. Well, Not exactly. Sure, meetings are unavoidable but they need not be long - and they definitely could be fun! How, you may ask, do you do that? By playing games! Intrigued? Well, the following strategies listed below illustrate how we employed games to make the decision making process a bit more entertaining.

The Planning Poker

We had an estimate of the time that was available. We also had a list of certain milestones that needed to be accomplished within this time frame. The quandary that was ostensibly placed before us was - could we accomplish all these milestones? If not, which ones do we prioritize? Sure, there were a lot of slick estimation tools available; however, most of them rely on historical data - something that was not available for our benefit in the Fall semester when we embarked on this project. The viable solution seemed to be the employment of past experiences of team members in order to arrive at a reasonable estimates - estimates that would prevent the plan from being entirely quixotic. To avoid inconclusive discussions and foster team enthusiasm, we decided to employ the game of planning poker. As indicated by the website http://www.planningpoker.com/ " The idea behind Planning Poker is simple. Individual stories are presented for estimation. After a period of discussion, each participant chooses from his own deck the numbered card that represents his estimate of how much work is involved in the story under discussion. All estimates are kept private until each participant has chosen a card. At that time, all estimates are revealed and discussion can begin again." In our case, the stories were milestones, where each member rationalized his estimates by discussing the tasks he believed were inherent within this milestone. Not only did this environ alleviate peer pressure, but it also fostered amusement in an otherwise mundane process.

The Task Selection Race

Based on historical performance, each team member had an upper limit on the tasks that they could place on their respective backlog. This task selection process was spiced up by incorporating race flags and lights on a central progress monitor. Its principle was simple - as each team member filled up their backlog queue, the indicators associated with their queue changed from green to amber. The goal was for each team member to select tasks until the indicator changed to red. The concomitant effect of this strategy was that team members tried to race each other to the finish line. Individuals who would otherwise deliberate indecisively on which tasks to select to their queue, were now subconsciously motivated to speed up their decisions and select the tasks that they found interesting. The overall effect was a drastic reduction in meeting duration and a dramatic improvement in excitement in what would otherwise be a mundane, repetitive process.

Rock, Paper, Scissor!

The simplest games too can come to you rescue! When all else fails, we decided to base our decisions on chance. Note that, this was used only in situations where all paths were feasible and only a selection had to be made in term of individual ownership. To cite an example, for determining a presenter for an event, this technique would come in handy to eliminate options and quickly arrive at a winner (some would call a loser!) who would take ownership for the task at hand.

Have fun!
The whole idea being this article (if you haven't figured out already) is that the workplace need not be boring! I have anecdotal evidence to support this, and believe that even the most mundane tasks can be transformed into something interesting. Arriving at decisions that are in conformance with multiple members is a daunting task, and can be quite demoralizing if they degenerate into long, inconclusive meetings. Why then, not speed up the process and have fun while at it?

Nodding Is Not Enough

Using nodding heads as criteria to determine team understanding, alignment, and commitment is kind of risky.

Wikipedia defines it. A nod of the head is a gesture in which the head is tilted in alternating up and down arcs. In many cultures, it is most commonly, but Not universally, used to indicate agreement, acceptance, or acknowledgment. [http://en.wikipedia.org/wiki/Nod_(gesture)]

I will define nodding as binary output from an individual with a "true" value in a giving context. Yes, I am nodding or not.

But, the million-dollar question is. What are you nodding to? What component in the diagram? What part of the plan? Remember it could also mean: Yeah Right! And I'm Chuck Norris!

Having said that, would you rely on nodding heads as way to determine people buy-in and understating in your project?

Well, this post is to foster software engineers to make their peers to "produce content" in their team interaction. Because nodding heads is not enough.

The reason why is important to make people generate content. Is that this is the only way ambiguities will surface. Many times it had happened to me that I thought I knew something, until I tried to do it. The same thing happens in a team. There are many misconceptions that need to be revealed, preferably as soon as possible depending in the criticality of the topic. It is your job to help catch them.

Now I am going to cover some of the activities that helped our team members identify misalignment and improve communication.

Daily Status Meeting (15 min)

We started every day with our daily standup meetings, which last no more than 15 minutes. In which people "produced content" answering three questions, what did you do yesterday, what are you doing today and do you have any issues? We also addressed any important reminder.

Common time & Cubicle Discussions:

Having all the team available at the same time in the same place. Is the best you can get. Having team members to talk in the cubicle open the opportunity for people to produce content by asking question, writing in the board or even thinking out loud.

All this availability of information lead to uncover many issues and solved them right away issues.

Status meetings (45minutes):

These helped the team to keep aligned with our plan, tracking data and quality.

In this meeting different team members had the opportunity to produce content (Planning, Tracking, Quality). An important lesson from these meetings was that presenting content in the similar format systematically kept people focused on the data.

Topic of the week and Sanity Checks:

This is an activity we did to proactively make people "produce content" on important topics such as architecture, processes and planning.This helped considerably to surface team misalignments.

As can be seen during our studio project we invested a lot in team communication.

However, that was not all. There were some software engineering practices that provided other communication channels. These were Fagan inspection and Pair programming. These practices complemented communication areas that were not covered with the previous techniques. Specifically, they improved knowledge transfer of coding practices and technology specific concepts. Also, Fagan and Pair Programming required continuous participation of different member to identify issues that could impact quality.

All this investment paid off with team alignment, good environment and a good client survey result. So, my recommendation is to have different ways to assess team alignment instead of assuming too much.