Coming to a software project later on, some things don’t tend to make sense. Why are there two services here instead of one? How come you are not using this way of message passing instead of that, why is your data format XML instead of JSON? Wait, you did not use a grid CSS layout?!

In my experience so far most of the answers to these questions are answered within the first 1,000 lines of code that you lay out in the beginning of the project whatever stack you might use you will run into similar (if not same) questions and you need to have the answers to such questions.

Lets face it, software design is as much artisan work as much as it is engineering.  Just like most paintings have a deeper story than what you can first spot in the beginning, most software architectures/designs have a story behind them. Unfortunately, as engineers by training (or scientists in my case) software crowd tends to get confrontational with black and white examples/dogmas when joining/taking over a project. Suggestions can be right or wrong, useful or futile, but if you can dodge most of the futile arguments and let people make the point for arguments that they strongly believe in the value of, why not do it?

But how do you make sure people argue something that is at least of some value to the project? Give them the best tool they can use: data.

In this case the data a software developer/architect needs usually falls into three categories:

1. Data Flow -> where is the data coming from, why is it stored there, why are you moving it around and how is this achieved?
2. Process Flow -> Why is the business process (even if you are writing a social photo sharing site there is a process flow don’t let the enterprisey word scare you) split over X number of nodes? How does this help you when considering scaling, response time and overall deployment plan?
3. Team Dynamics -> Certain decisions are not always made in the light of sole technical sense. When there are two people on a project there is politics. Sometimes compromises need to be made to move projects forward. Best one can do in this case is to explain the thought process of what was considered, and why it was not chosen.

You might say, isn’t all this already there in code, database, emails? Yes it is there. Unfortunately for us though, no one goes back to hunt information. Part of your job, especially as an architect, is to make sure you collect/present/maintain this data. The reason present is bold is for (maybe not) obvious reasons; the quality of telling the story is just as important as the story itself.

Doesn’t sound exciting but this is the single best thing you can do if you want to have a cohesive technical team that works together despite differences in opinion.