signiﬁcant design decisions that shape a system, where signiﬁcant is measured by cost of change.” Application Architecture: Concerns a particular application, sub-system or project. Considers design patterns, languages, libraries and frameworks System Architecture: Concerns the interop and integration of multiple services and applications, inc software and hardware and network considerations. Enterprise Architecture: Concerns organisation, people and processes.
and development. There is no one way to write an ADR, but most are based on http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions Title: Short but discoverable label Context: What’s the problem? What’s the effect? Why did that problem come about? Facts, not assumptions or opinions. Decision: What should happen to solve or mitigate the issue? How is success deﬁned? What further recommendations are there? What alternative solutions were ruled out, and why? Status: The status of the work described, a dated list of status changes works well. Consequences: The resulting context. Good and bad, what is the effect of work described?
ADRs should be considered to be lightweight records of decision making, linking in other documents and content as appropriate, keeping the ADR itself succinct and to-the-point It can live anywhere, in any format. Discoverability is important.
the team. They work best when the decisions are jointly owned. They should be considered living documents, providing useful documentation throughout the life of a project. They provide a common framework for the communication of technical decisions, allowing engineers of all levels a consistent way of inﬂuencing strategy. Having a clear, supportive process around ADRs allows the democratisation of architecture, strong team alignment, and an effective foundation to mentoring broader engineering concepts.
Report Build & monitor, or reject Inception Every stage in the software development lifecycle (SDLC) will feed into one or more ADRs Each iteration of ADRs uses the context created by the last set of decisions An ADR itself does not have inﬂuence over the process, it is not a hand over document, nor a prerequisite. ADRs can be a signiﬁer of an effective design process within the SDLC
in the software development life cycle” - Wikipedia. Although not directly linked to ADRs, the process should support architectural design and result in the documentation of decisions and trade-offs. ATAM formally proposes nine steps, but these can be summarised as four phases Present process and context Exploration / Discovery Review & Evaluate Report
through different scenarios documented as stimulus and response. Prioritisation is done along two dimensions: importance to the success of the system and the perceived risk to achievement. “(H,M) Deliver video in real time” is of high importance to the success of the project, but achieving that goal has medium risk.
purchase journey not be faster than 6 sec Performance Each page loads in <2 sec Stock check returns <2sec Security No risk from client based attack vectors (Usability) No ability to add delivery notes or update address and billing info Usability User can purchase product in 3 clicks A simpliﬁed Utility Tree, which pairs well with ADRs and can be done collaboratively to assess and review decisions
deliver a piece of functionality, the scope of the work is functionally-boxed. Incremental architecture requires more up-front design, and realises risks later, but may decrease cost of delivery. An iterative approach requires cycles of design and development that are time-boxed to create a continually improving system. An iterative architecture reduces cost of design but may increase cost of delivery. Architecture decisions need to consider both models, assessing risks and business delivery objectives to decide how to design, build and learn for a given requirement
enables near-term or concurrent development. Deferring decisions ensures that the most knowledge and experience is available. Just enough design has been described as sitting “in the chasm between Big Design Up Front’s 'analysis paralysis' and Emergent Design’s 'refactor distractor'” - Simon Brown, author of the C4 model (1) In the book Lean Software Development: An Agile Toolkit, Mary and Tom Poppendieck describe iterative design/development: “Concurrent development makes it possible to delay commitment until the last responsible moment, that is, the moment at which failing to make a decision eliminates an important alternative.” (1) http://www.codingthearchitecture.com/
victory” strategy is based on the work of sociologist Karl Weick (1), showing that achieving results helps people come to trust each other more, raises morale and helps them perform better. Architectural decision making to should consider “Early victory” to prioritise small meaningful wins. At the beginning of a project it is often wise to implement a “Walking Skeleton” to provide an early victory to the team and stakeholders. It’s the ﬁrst deliverable, a thin end-to-end implementation which exercises the core architecture, de-risking potential design ﬂaws and known constraints. 1) https://www.amazon.co.uk/Crystal-Clear-Human-Powered-Methodology-Small/dp/02 01699478 2) Karl Weick, The Social Psychology of Organizing, McGraw-Hill Humanities/ Social Sciences/Languages; 2nd edition, 1979.
are copies of the communication structures of these organizations." - Melvin Conway, from his 1968 paper “How do Committees Invent?” The law can explain contention in architecture, rooted not from poor design but by poor organisation. The 'Inverse Conway Maneuver' recommends evolving team and organizational structure to support the desired architecture. Ideally this architecture will display isomorphism with your business architecture. When making architectural decisions it’s important to understand how the organisation may affect the success of that architecture; and if appropriate, suggesting organisational change to align with the goals of the proposed architecture.