I’d like to point out an important thing about Architecture Decisions Records (ADR). An ADR records a decision and the context it was made in. A decision record should not be used to try and capture all of the information relevant to an architecture or design topic.
The creators of an architecture or design should author a document that describes it in detail (whether facilitated by a guild or not). Authors should:
- research the matter problem and solution space
- think about how solutions will fare in their environment
- experiment to (in)validate critical hypothesis
- capture their findings in written form
The process of creating a design might take a couple of days or weeks.
Once a design’s authors have captured information in reviewable form, they can proceed to socialize that design. Reviewers can review the design and provide feedback in this phase. Once authors and reviewers are in agreement on a matter (or two!), they can record a decision.
This is why writing an ADR should only take an hour or two.
The ADR is a snapshot of information uncovered during the creation process. If you try to make a decision without this information, you’ll likely find yourself in frustrating decision reviews that end-up kicking a decision down the road.
Once you have a decision, you can adopt it throughout your organization. You’ll want to share the decision and/or design through channels to ensure relevant people know about it, probably multiple times. Then authors can help people use it and gather real world feedback to refine future iterations of the design.
Bottom Line: A successful architecture decision-making and recording process depends on creating and socializing a design doc on the matter first.
#NoDrama
