I have written here before about Architecture Decision Records. I want to dig into this topic more deeply here.
Why
Why do we need to put effort into making sure developers, and others, are kept up to date with architectural decisions and guidelines?
In order to build a cohesive system together, we must share a common vision. We are very familiar with this concept for the organization in general. The organization as a whole has a shared vision. The technology department has a shared vision. These visions are useful, but they are usually along the lines of “become the leader in our space and crush the competition” which doesn’t really help the developers build a system. Therefore, we must have some kind of shared technological vision for the system.
Product shares their vision for the system quite visibly in the form of user stories. Just like architects, product folks make certain decisions about the application. They make decisions on what it will do and won’t do. They decide that it should have a mobile interface, or a speech interface. These decisions are quite prominent, and very impactful to the application and system as a whole.
Likewise, architectural decisions are very impactful, though sometimes less prominent. To an end user it doesn’t matter much if the web page is built on Vue.js, React, JSP, or custom hand-built HTML and JavaScript. Any of these technologies could probably fulfill the strict user story requirements. Yet each one has major consequences for how the developers will actually build the system. If somebody decides that the UI should be built with Vue, but doesn’t tell the developers that, they shouldn’t be surprised when they find the UI was actually written in JSP.
How
How do we communicate decisions? If we need to be able to tell the team developing the UI that we favor one technology over another, or we need to support something Product isn’t talking about (such as response times), how do we actually accomplish that?
The Architecture Decision Records are one way. But not everybody will actually read or pay attention to those. Maybe this is a cultural problem specific to certain companies, but not everybody will follow the updates to decisions. You can try to broadcast them out, but people can still just ignore you. Sometimes they will ask about how to do something, and you can point them back at the records or other communications. Other times they will just do something their own way. This may be caught, late in the game, and then you have to deal with the issue of making them go back and “fix it”, pointing back to the documentation and communication saying how it should have been done in the first place, or letting it slip by.
Some evil people will even keep up to date on the decisions, see the update, not like the decision, and still do it their own way. When this then is pointed out, they say there’s no time to “fix it”, there’s already pressure from “the business” to move on to the next critical thing.
Overcoming Issues
On top of all the previous communication issues, people can also just get tired. They do not have poor intentions or anything, but they just do not keep up to date, or don’t remember that something has changed and should be done a new way. What are some ways to overcome all these issues?
One way is to embed architecture with the teams. Become members of the teams, participating in their scrum and sprints, working some of the stories on their board. In this way, you will be kept up to date when something comes up that either needs an architectural decision, or has already been decided. The team can immediately be nudged in the right direction. This method also helps build trust, and keeps the architects from living in an Ivory Tower, giving commands from armchairs and mixing metaphors.
Another technique that I’ve seen success with is to have real live architecturally sound templates, based on reference architectures. Have a set of barebones template services readily available and kept up to date with the current best practices. Any time a new service needs to be created, they start from one of these templates. These are also very useful when revisiting an old service that hasn’t been touched in a while. They provide an example for how to upgrade pieces of that old service that may now be out of date.
Do you have any other useful ways to overcome these communication barriers?