Architecture Decision Records and process

Originally presented at MOO in 2018. This presentation covers a summary of Architecture concerns, supporting processes and documentation through ADRs.

https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=5177

Transcript

3. Grady Booch (Best known for developing UML) “Architecture represents the significant design decisions that shape a system, where significant 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.
4. The “Utility” of the system, sometimes referred to as the ‘ilities’, can be defined though: • Accessibility (e.g AAA WAI compliance) • Availability (SLA, HA, five nines) • Interoperability • Maintainability (e.g. Mean Time To Repair - MTTR) • Modifiability • Performance • Reliability (e.g. Mean Time Between/To Failures - MTBF/MTTF ) • Scalability (horizontal, vertical) • Security • Testability • Usability ...etc
5. Architecture Decision Records document decisions and trade-offs made during design 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 defined? 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?
7. Jira Epic / Milestone Spikes Supporting docs ADR Diagrams Code 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.
8. ADRs can and should be written by any engineer in 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 influencing 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.
10. Present process and context Exploration / Discovery Review & Evaluate 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 influence over the process, it is not a hand over document, nor a prerequisite. ADRs can be a signifier of an effective design process within the SDLC
11. Architecture Tradeoff Analysis Method “...is a risk-mitigation process used early 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
12. Present process and context Exploration / Discovery Review & Evaluate Report ATAM Utility Tree Spike Jira Epic ADR
14. https://resources.sei.cmu.edu/asset_files/TechnicalReport/2000_005_001_13706.pdf The “Utility” of the proposed system can be defined 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.
15. Success goal Trade-off Modifiability Pages are separately deployable (Performance) User 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 simplified Utility Tree, which pairs well with ADRs and can be done collaboratively to assess and review decisions
16. An incremental approach requires numerous sequential steps to design and 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
17. It’s important to focus design activities in a manner that 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/
18. Described by Agile Manifesto author, Alistair Cockburn (1), The “early 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 first deliverable, a thin end-to-end implementation which exercises the core architecture, de-risking potential design flaws 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.
19. "Organizations which design systems are constrained to produce designs which 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.