Capturing notable architectural decisions
Neil B. Harrison, George Rudolph, Jingpeng Tang, Lynn Roy Thackeray, David A. Wagstaff · 2023
The inherent complexity of a software system of any size requires intentional design of the architecture. Numerous tools have been developed so support recording architecture decisions, but generally architecture decisions remain inadequately documented. Architecture decisions are generally recorded as text, but the ideas do not lend themselves to textual representation. One obstacle to documenting architecture decisions is the inherent difficulty of capturing the decisions themselves. It can be difficult to remember to document a decision when it is made. We propose focusing on recording "Notable Decisions", those that require explicit documentation. We identified characteristics of such decisions. We conducted a limited controlled experiment to investigate the nature of notable decisions. Preliminary results indicate that most of the decisions made were obvious, but some were notable and needed explicit documentation, suggesting that focusing on documenting notable decisions may be useful.