Note: This article, along with Architecture Records Metamodel, is being published in advance of the publication of the Solution assets, which will follow later in 2024.
Content
Purpose and Value
Introduction
“Architecture represents the set of significant design decisions that shape the form and the function of a system”
Grady Booch [1]
In the above quotation, Grady Booch highlights that an architecture is, in essence, the sum of the significant design decisions that have been taken. And as Michael Nygard has pointed out, “Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.” [2]
The Architecture Records Solution introduces a decision record framework to facilitate the creation and maintenance of different types of architecture records. The framework approach allows Ardoq customers to decide which types of decisions they wish to record in Ardoq, and to develop their own preferred structure for each architecture record type.
In addition to supporting conventional Architecture Decision Records (ADRs), this solution also supports Pattern Descriptions, Approved Standards, Exception Requests and Compliance Assessments. These are all, in their own way, forms of decision records.
The records become an integral part of Ardoq’s knowledge graph, enabling them to play a full role as an element in the overall architecture repository. For example, a decision record may be the starting point of a question, the answer to which is the set of technical components that comprise a particular solution architecture.
Purpose
The purpose of this Solution is to facilitate the creation and management of different types of architecture records in Ardoq. It allows users of Ardoq to answer the following questions:
Which decisions have contributed to the architecture of a given part of our enterprise (which may relate to the organization and its people, processes, information, applications or supporting technologies)?
What was the rationale that led to a particular decision?
What alternatives were considered?
What is the status of the decision?
When was the decision made, and who approved it?
What period does the decision cover?
When should it be renewed or reconsidered?
What past decisions have been made that are no longer current?
Which principles or quality characteristics have driven the decision?
What other decisions are related to this one?
Delivering value with this Solution
The solution provides value in the following ways:
Articulating decisions - documenting the why and the why not
Socializing decisions
Supporting audit and regulatory requirements
Tracking decisions - using automation to keep information up to date
Articulating decisions
Architectures tend to outlive their architects. This is as true of enterprise, business, solution and information architectures as of buildings. Long after the architect has moved on, the fruits of their work are in daily use and will need ongoing maintenance. How a thing has been architected will be discoverable, but just examining the thing will not tell you Why it has been architected in a particular way, nor Why Not in a different way. Some agile development enthusiasts have argued that there is no need to separately articulate a solution architecture because “the code is the design” [3]. But as Ruth Malan, Architecture Consultant at Bredemeyer Consulting, points out:
“If we don't understand what system integrity means for our system, how do we maintain it? Further, in evolving the system, we want to assess whether the founding assumptions and shaping forces still hold — does the design still make sense? What do we retain? What design philosophy and principles, structures and mechanisms do we preserve to preserve structural and design integrity. and what can we make accommodations to and shift?” [4]
Socializing decisions
Good governance is an essential element of successful enterprise architecture management. This solution allows the enterprise architecture team to socialize decisions. When used in conjunction with Ardoq Discover, architecture records can be easily searched. The structured approach adopted for architecture records encourages clear articulation of architectural decisions, helping a team gain buy-in to its approach and educating stakeholders about the relationship between architecture guiding principles, quality characteristics and the decisions that have been taken.
Supporting audit and regulatory requirements
For many organizations, maintaining a register of decisions is a regulatory requirement. The Solution makes it easy for architecture teams to support audit investigations and other forms of review, such as post-implementation review.
Tracking decisions
Leveraging Ardoq’s distributed workflow capabilities, combining Surveys with Broadcasts, the Solution offers automated processes to support distributed decision making, approvals by individuals, or more formal approvals by bodies such as an Architecture Review Board, and reminders for repeated decisions, such as renewal of approved standards or exception requests.
Scope and Rationale
The Ardoq Solution Metamodel contains a component type to represent a document such as an architecture record: the Information Artifact. This solution extends that component type with additional fields and references so that it can be used to represent a range of documents that describe different kinds of decision. These give users a structured way of organizing the information associated with a decision, rather than trying to describe all aspects of a decision in a single Rich Text field.
Christopher Alexander’s approach to structuring design patterns has become widely adopted as a way of organizing and articulating architectural decisions. The following section provides a brief introduction to Alexandrian Patterns and explains how it has inspired the templates for five different types of Architecture Records.
Alexandrian Patterns
Christopher Alexander is widely acknowledged as the originator of pattern languages [5]. The structure he introduced in his pattern language for towns, buildings, and construction has been adopted and adapted to suit a wide range of domains, including patterns for enterprise and IT architectures. At its simplest, an Alexandrian pattern is a three-part rule expressing a relation between:
A certain context
A problem
A solution
This basic structure suits a wide range of decision records, including but not limited to Design Patterns. There are a number of widely shared templates for Architecture Decision Records (ADRs) [2], [6], [7], all of which follow the Alexandrian form.
It is not surprising that the Alexandrian form has proved suitable beyond the scope of pattern descriptions, since pattern descriptions and other types of architecture record have a lot in common. While a pattern description has, as its goal, the encouragement of its reuse, they all have a strong need to articulate not just the “what” of a decision, but also the “why”, and perhaps also the “why not” of alternatives. One popular ADR template is Olaf Zimmermann’s Y-Statement, which has the following template:
In the article introducing the approach [6], he gives the following as a worked example:
In the context of the Web shop service,
facing the need to keep user session data consistent and current across shop instances,
we decided for the Database Session State pattern
and against Client Session State or Server Session State
to achieve data consistency and cloud elasticity,
accepting that a session database needs to be designed and implemented. |
Types of Architecture Record
In addition to ADRs and Patterns, there are other specialized decisions that can benefit from the Alexandrian structure, or a variant of it.
This solution presents an extensible framework that allows Ardoq customers to choose a set of architecture record types to record and manage in Ardoq, and apply a standard structure to each type, drawing on a collection of fields with which they can “compose” a template to suit each of their architecture record types. Included with the solution are examples of the following architecture record types:
Decision Record
Pattern Description
Compliance Assessment
Architecture Standard
Exception Request
Decision Records can be used to represent the results of more substantial architecture reviews (such as ATAM [8] or SARM [9] Trade-off Analyses), but full support for these reviews, which involve evaluating architectures from the perspectives of different quality characteristics and relating them to Architecturally Significant Requirements [10], are outside the scope of this Solution. Support for reviews is planned for a future Solution in the Architecture Quality series.
Evaluations and Reviews
Architecture evaluations and reviews might be considered “extended family members”, closely related to the five core family members listed above. However, supporting these activities demands more than a structured set of text or list fields and are outside the scope of this Solution. It is, of course, possible to capture the results of such reviews with a Decision Record component (or a Compliance Assessment if the review has the notion of Pass or Fail).
The Raw Ingredients
Fields
The following table lists the set of fields from which a selection can be made to populate a particular “architecture record” component type.
Field Name | Field Type | Definition |
Decision Context | Text paragraph | The context or use case that lies behind the architecture record. |
Decision Concern | Text paragraph | The particular concern that prompted the need for the architecture record. |
Decision YesNo | List | The decision (a Yes or No). |
Decision Text | Text paragraph | The decision (a text paragraph describing the decision). |
Decision Rationale | Text paragraph | A description of the rationale behind the decision and the desirable outcomes that will follow. |
Decision Assumptions | Text paragraph | A list of the assumptions that lie behind the decision. |
Decision Consequences | Text paragraph | A description of the consequences of the decision, including any downsides. |
Review Date | Date Time | The date this component was last reviewed. |
Next Review Date | Date Time | A forward date when this component should next be reviewed. |
Decision Live | Date Range | A date range representing the period during which this decision applies / has currency. |
Decision Status | List | One of: Proposed, Rejected, Approved, Retired |
The fields Decision YesNo and Decision Text are alternatives. In some circumstances, the component represents a record that has a clear binary decision, such as a compliance assessment considering this question: Does this component fall within the scope of a given policy? So a Compliance Assessment can use Decision YesNo. For a more general Decision Record, the text paragraph as provided with Decision Text is more suitable.
See the Architecture Records Metamodel for details of our recommended selection of fields for each Architecture Record type.
References
Three Reference types are available for use with Architecture Records:
Has Subject - a reference used to point from the Architecture Record to the component or components that are the subject of the record (e.g. pointing from an Architecture Standard component to the component that is the proposed or approved standard);
Refers To - a reference type used to link the Architecture Record to any component that is not the “subject” of the Record but is associated with, or provides evidence for, the record (e.g. pointing to the quality characteristics that underpin an architecture decision record);
Approved By - a reference type from the Architecture Record to one or more Person components signifying that the Person has approved the Architecture Record.
Bibliography
[1] Grady Booch [@Grady_Booch], “All architecture is design, but not all design is architecture. Architecture represents the set of significant design decisions that shape the form and the function of a system, where significant is measured by cost of change.,” Twitter. Accessed: Jun. 17, 2024. [Online]. Available: https://x.com/Grady_Booch/status/1459007228954832896
[2] M. Nygard, “Documenting Architecture Decisions,” Cognitect.com. Accessed: Jun. 17, 2024. [Online]. Available: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
[3] J. W. Reeves, “What is Software Design?,” C J., 1992.
[4] R. Malan, “The Code is the Design? | LinkedIn.” Accessed: Mar. 25, 2024. [Online]. Available: https://www.linkedin.com/pulse/code-ruth-malan/
[5] C. Alexander, A Pattern Language: Towns, Buildings, Construction. New York: OUP USA, 1978.
[6] O. Zimmermann, “Y-Statements,” ZIO’s Blog. Accessed: Jun. 17, 2024. [Online]. Available: https://medium.com/olzzio/y-statements-10eb07b5a177
[7] ADR GitHub, “Architecture Decision Records.” Accessed: Jun. 17, 2024. [Online]. Available: https://adr.github.io/
[8] R. Kazman, M. Klein, and P. Clements, “ATAM: Method for Architecture Evaluation,” Software Engineering Institute, Carnegie Mellon University, Technical Report CMU/SEI-2000-TR-004, Aug. 2000.
[9] S. Field, “SARM,” SARM: A site devoted to the Solution Architecture Review Method. Accessed: Feb. 14, 2024. [Online]. Available: https://sarm.org.uk/welcome/
[10] “Architecturally significant requirements,” Wikipedia. Aug. 13, 2023. Accessed: Jun. 17, 2024. [Online]. Available: https://en.wikipedia.org/w/index.php?title=Architecturally_significant_requirements&oldid=1170100577