Architecture Decision Records

While formulating the Architecture of a software solution, many decisions are taken after careful consideration of various factors that originate from the customer, Architect's tacit knowledge and the platform capabilities. But the rationale for taking a given decision is seldom documented. In other words, the design philosophy behind the architecture is rarely documented. While existing architects know, having worked closely with each other, what that philosophy or rationale was, if the architecture needs to be owned by another architect and designers in the future, they will have no clue about the thought process that went behind it. When an Architect leaves the organization, that knowledge goes along with the individual. Organizations cannot afford to let this happen. Many times the knowledge transfer exercise that takes place when an architect leaves the team or the organization, is very reactionary. An architect can easily miss certain important aspects that occurred in the very early stages of the delivery. As a result, a future architecture team who inherits the architecture will struggle to understand why the architecture is designed in a particular way.

The design philosophy behind the architecture is rarely documented.

Architecture Decision Records is a way by which this can be avoided. This may be an independent repository that architects can maintain or it may be part of a Solution Architecture Specification.

At a minimum, following details may be captured:

• Architecture component or impacted area
• Problem statement
• Alternatives considered
• Decision made
• Rationale for the decision
• Risks, if any, with the decision
• Limitations, if any, with the decision

But why is this not followed or done effectively? There are multiple reasons:

1. When a team is working under lot of delivery pressure, focus is generally on getting the solution out the door rather than worrying about who will maintain this in the future.
2. Unless the delivery team is adequately staffed so that the Solution Architect can remain focused on such aspects, it is very difficult to find time to maintain this information. The cost pressure, ballooning scope, delivery delays, etc., contribute to dilute the focus on capturing these for posterity.
3. Procrastination: Many times documentation gets lower priority over delivery commitment and hence the former is often pushed to the back burner. But the more this is delayed, the less one remembers the finer details to be captured. The risk of certain decisions being missed out also increases.
4. Reactive approach: Many times this is done when the Architect is about to leave the team or the organization. In such cases it is often done in a rush, as a tick in the box exercise.

A software solution leading a healthy life is as important as it being born healthy. That is possible only if architects enable the inheritors of the software to read the former's mind to understand the philosophy of the architecture.

Lest the unspoken architecture philosophy ruin the software.