From f44b892b1ce5fdcc5422073784b4f0be57469799 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 14:33:38 +0100 Subject: [PATCH 01/50] Refactoring: split index page --- index.md | 75 +++++++++++++++++++++++++++----------------------------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/index.md b/index.md index 1fe47eb..6493227 100644 --- a/index.md +++ b/index.md @@ -2,8 +2,11 @@ layout: default mermaid: true --- + # Architectural Decision Records (ADRs) +## Motivation and Definitons + An [Architectural Decision (AD)](https://en.wikipedia.org/wiki/Architectural_decision) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An [Architecturally Significant Requirement (ASR)](https://en.wikipedia.org/wiki/Architecturally_significant_requirements) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An *Architectural Decision Record (ADR)* captures a single AD and its rationale; @@ -22,21 +25,25 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADRs in the Media +- 10/11/2024: The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) at Microsoft Ignite features ADRs and this website. - [Love Unrequited: The Story of Architecture, Agile, and How Architecture Decision Records Brought Them Together](https://ieeexplore.ieee.org/document/9801811), Michael Keeling in the Pragmatic Designer column of IEEE Software Vol. 39 Issue 4 (2022) ([PDF](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9801811)) -- Chapter 3 of ["Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges"](https://api-patterns.org/book/) in the Addison Wesley Signature Series at Pearson features six narratives guiding through the conceptual level of API design: 29 recurring decisions with options and criteria. Learn more in this [blog post](https://medium.com/nerd-for-tech/api-patterns-website-redesigned-and-sample-book-chapter-available-df9daf4b5e15). - Architectural decision capturing is positioned as one of the essential activities in [Design Practice Reference](https://leanpub.com/dpr), a LeanPub e-Book. -- (German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). +- Chapter 3 of ["Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges"](https://api-patterns.org/book/) in the Addison Wesley Signature Series at Pearson features six narratives guiding through the conceptual level of API design: 29 recurring decisions with options and criteria. Learn more in this [blog post](https://medium.com/nerd-for-tech/api-patterns-website-redesigned-and-sample-book-chapter-available-df9daf4b5e15). +- (in German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). {: .long} -## Lightweight ADRs Should be Adopted +## ADRs in a Nutshell + +A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). -A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) (according to [@mtnygard](https://github.com/mtnygard)). -[ThoughtWorks](https://www.thoughtworks.com/) listed architectural decision records as "adopt" at their [technology radar vol. 18](https://assets.thoughtworks.com/assets/technology-radar-vol-18-en.pdf): + -We think that the considered options with their pros and cons are crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/) --- The Markdown Any/Architecture Decision Records (MADR: `[ˈmæɾɚ]`) in this ADR organization includes such tradeoff analysis information. +We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Any/Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. -## Relation of ADRs, MADR, and Others +## Relation of Nygardian ADRs, MADR, and Other Templates ```mermaid classDiagram @@ -45,14 +52,28 @@ classDiagram <> } ADR <|-- MADR - ADR <|-- YStatement - ADR <|-- Nygard + ADR <|-- Y-Statement + ADR <|-- NygardADR + ADR <|-- OtherADRTemplate ``` ## Sustainable Architectural Decisions -We base our work on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. -However, we are open to other formats of ADRs as shown at [@joelparkerhenderson's repository](https://github.com/joelparkerhenderson/architecture_decision_record). +The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. + +## Existing ADR Templates + +Many ADR formats exist, as shown at [@joelparkerhenderson's repository](https://github.com/joelparkerhenderson/architecture_decision_record): + + +- [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`). Lean ADRs to quickly document architectural decisions in code. Slogan: architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). +- [DecisionCapture](https://schubmat.github.io/DecisionCapture/): Templates for agile projects and explanation of the ADR universe, with [example](https://github.com/schubmat/DecisionCapture/blob/master/samples/samples_merged/samples_simpleTemplate_secondSprint.md). +- cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. +- The [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. + +A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. + +### Y-Statements In short, the Y-statement is as follows: @@ -70,25 +91,6 @@ The long form of it is as follows (extra section "because"): You can find more explanations and examples on Medium [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). -[A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. - -## Existing ADR Templates - -- Overview: [Architectural Decision Records](https://github.com/joelparkerhenderson/architecture_decision_record): collection of markdown templates converted to Markdown -- [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`). Lean ADRs to quickly document architectural decisions in code. - Slogan: architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). -- Comparison of seven templates: [Architectural Decision Guidance Across Projects - Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf). WICSA 2015: 85-94. -- Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). -- [DecisionCapture](https://schubmat.github.io/DecisionCapture/): Templates for agile projects and explanation of the ADR universe, with [example](https://github.com/schubmat/DecisionCapture/blob/master/samples/samples_merged/samples_simpleTemplate_secondSprint.md). -- cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. -- The [template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. - -## Good ADRs (and how to get to them) - -- [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns -- [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) -- [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) -- Proposal for [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) -- [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list ## Decision Capturing Tools @@ -136,17 +138,12 @@ For a more detailed list for tooling for MADR, please head to From a001fc288bc1ca2cec6377c50e204690395c24aa Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 14:34:06 +0100 Subject: [PATCH 02/50] New practices page --- _tabs/adr-practices.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 _tabs/adr-practices.md diff --git a/_tabs/adr-practices.md b/_tabs/adr-practices.md new file mode 100644 index 0000000..8580f42 --- /dev/null +++ b/_tabs/adr-practices.md @@ -0,0 +1,41 @@ +--- +icon: fas fa-briefcase +order: 4 +title: AD Practices +--- + +# AD Management Practices + +## AD Making + +Method selection and tailoring in DPR, the [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book. Architectural decision capturing is positioned as one of the essential activities in DPR. + +- [Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. + +## Good ADRs --- and how to get to them + +*Disclaimer:* +The lists on this page point at ADR capturing ptrsactices and related advice but do not necessarily endorse all of them. + +Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: + +1. START [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html) +2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) +3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. +4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) +5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. +6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). +7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list +8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) + +Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). + +Other articles: + +- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser +- More will be featured in future versions of this page, suggestions are welcome! +- *to be continued* + +## From Architectural Decision to Design/Any Decisions + +[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. \ No newline at end of file From 7964b7f03d527d8a89d52bc585c9f3d7a8a33c06 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 14:45:22 +0100 Subject: [PATCH 03/50] Fixes and light edits --- _tabs/adr-practices.md | 10 +++++----- index.md | 12 +++++++----- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/_tabs/adr-practices.md b/_tabs/adr-practices.md index 8580f42..6f8953e 100644 --- a/_tabs/adr-practices.md +++ b/_tabs/adr-practices.md @@ -8,16 +8,16 @@ title: AD Practices ## AD Making -Method selection and tailoring in DPR, the [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book. Architectural decision capturing is positioned as one of the essential activities in DPR. +The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. -- [Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. +[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. ## Good ADRs --- and how to get to them *Disclaimer:* The lists on this page point at ADR capturing ptrsactices and related advice but do not necessarily endorse all of them. -Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: +### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: 1. START [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html) 2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) @@ -30,12 +30,12 @@ Authored by one or more of the maintainers of `adr.github.io/` and the MADR proj Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). -Other articles: +### Third-party articles - [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser - More will be featured in future versions of this page, suggestions are welcome! - *to be continued* -## From Architectural Decision to Design/Any Decisions +## From Architectural Decisions to Design/Any Decisions [From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. \ No newline at end of file diff --git a/index.md b/index.md index 6493227..119b5d4 100644 --- a/index.md +++ b/index.md @@ -25,7 +25,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADRs in the Media -- 10/11/2024: The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) at Microsoft Ignite features ADRs and this website. +- The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) at Microsoft Ignite features ADRs and this website (10/11/2024). - [Love Unrequited: The Story of Architecture, Agile, and How Architecture Decision Records Brought Them Together](https://ieeexplore.ieee.org/document/9801811), Michael Keeling in the Pragmatic Designer column of IEEE Software Vol. 39 Issue 4 (2022) ([PDF](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9801811)) - Architectural decision capturing is positioned as one of the essential activities in [Design Practice Reference](https://leanpub.com/dpr), a LeanPub e-Book. - Chapter 3 of ["Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges"](https://api-patterns.org/book/) in the Addison Wesley Signature Series at Pearson features six narratives guiding through the conceptual level of API design: 29 recurring decisions with options and criteria. Learn more in this [blog post](https://medium.com/nerd-for-tech/api-patterns-website-redesigned-and-sample-book-chapter-available-df9daf4b5e15). @@ -89,7 +89,7 @@ The long form of it is as follows (extra section "because"): > accepting ``, > because ``. -You can find more explanations and examples on Medium [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). +You can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). ## Decision Capturing Tools @@ -139,11 +139,13 @@ For a more detailed list for tooling for MADR, please head to + +More pointers can be found at [Architectural Knowledge Management (AKM) overview](https://www.ost.ch/de/forschung-und-dienstleistungen/informatik/ifs-institut-fuer-software/labs/cloud-application-lab/architectural-knowledge-management-akm). + + From 7b3149550b5f4c3a978bacd9533485c161dbe4bf Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 14:50:29 +0100 Subject: [PATCH 04/50] Final fixes and light edits --- _tabs/{adr-practices.md => ad-practices.md} | 2 +- index.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename _tabs/{adr-practices.md => ad-practices.md} (98%) diff --git a/_tabs/adr-practices.md b/_tabs/ad-practices.md similarity index 98% rename from _tabs/adr-practices.md rename to _tabs/ad-practices.md index 6f8953e..8f119b0 100644 --- a/_tabs/adr-practices.md +++ b/_tabs/ad-practices.md @@ -12,7 +12,7 @@ The [Design Practice Repository](https://socadk.github.io/design-practice-reposi [Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. -## Good ADRs --- and how to get to them +## Good ADRs --- and How to Get to Them *Disclaimer:* The lists on this page point at ADR capturing ptrsactices and related advice but do not necessarily endorse all of them. diff --git a/index.md b/index.md index 119b5d4..21c4278 100644 --- a/index.md +++ b/index.md @@ -138,14 +138,14 @@ For a more detailed list for tooling for MADR, please head to -More pointers can be found at [Architectural Knowledge Management (AKM) overview](https://www.ost.ch/de/forschung-und-dienstleistungen/informatik/ifs-institut-fuer-software/labs/cloud-application-lab/architectural-knowledge-management-akm). +More pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). From a47147f70c5230e0bc36e7281ea106e7d3f2319d Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 14:54:10 +0100 Subject: [PATCH 05/50] ITARC presentation link --- _tabs/ad-practices.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 8f119b0..09ad7e8 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -6,6 +6,8 @@ title: AD Practices # AD Management Practices +[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. + ## AD Making The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. From 03da50d1bba1cc8eeade74437bd47094cbb6c142 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 15:04:18 +0100 Subject: [PATCH 06/50] Bug fixes --- _tabs/ad-practices.md | 10 +++++----- index.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 09ad7e8..21af1f4 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -4,7 +4,10 @@ order: 4 title: AD Practices --- -# AD Management Practices +# AD Practices + +*Disclaimer:* +The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. [Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. @@ -16,12 +19,9 @@ The [Design Practice Repository](https://socadk.github.io/design-practice-reposi ## Good ADRs --- and How to Get to Them -*Disclaimer:* -The lists on this page point at ADR capturing ptrsactices and related advice but do not necessarily endorse all of them. - ### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: -1. START [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html) +1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. 2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) 3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. 4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) diff --git a/index.md b/index.md index 21c4278..fea9db5 100644 --- a/index.md +++ b/index.md @@ -5,7 +5,7 @@ mermaid: true # Architectural Decision Records (ADRs) -## Motivation and Definitons +## Motivation and Definitions An [Architectural Decision (AD)](https://en.wikipedia.org/wiki/Architectural_decision) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An [Architecturally Significant Requirement (ASR)](https://en.wikipedia.org/wiki/Architecturally_significant_requirements) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. From d7fd3beffab86eb5d1b3dc581fd278cb24799c39 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:06:57 +0100 Subject: [PATCH 07/50] Fix heading --- _tabs/ad-practices.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 21af1f4..6e38ba6 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -4,8 +4,6 @@ order: 4 title: AD Practices --- -# AD Practices - *Disclaimer:* The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. @@ -40,4 +38,4 @@ Most of the material referenced above is also available on [Medium](https://medi ## From Architectural Decisions to Design/Any Decisions -[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. \ No newline at end of file +[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. From ac1dcf2f5fb6fc00a5379d1032a182fa0f765070 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:07:35 +0100 Subject: [PATCH 08/50] Fix icon --- _tabs/ad-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 6e38ba6..fe83e76 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -1,5 +1,5 @@ --- -icon: fas fa-briefcase +icon: fas fa-check-circle order: 4 title: AD Practices --- From bcd72860c09c6014c964290450855d9aaedd0c7c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:08:52 +0100 Subject: [PATCH 09/50] Remove obsolete tag --- index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/index.md b/index.md index fea9db5..86a6755 100644 --- a/index.md +++ b/index.md @@ -31,7 +31,6 @@ The repository for the Website of the ADR organization is [https://github.com/ad - Chapter 3 of ["Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges"](https://api-patterns.org/book/) in the Addison Wesley Signature Series at Pearson features six narratives guiding through the conceptual level of API design: 29 recurring decisions with options and criteria. Learn more in this [blog post](https://medium.com/nerd-for-tech/api-patterns-website-redesigned-and-sample-book-chapter-available-df9daf4b5e15). - (in German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). -{: .long} ## ADRs in a Nutshell From 047e25b68ae02c7f05059017dc7980b972291087 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 15:23:57 +0100 Subject: [PATCH 10/50] Own section for MADR on homepage --- index.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/index.md b/index.md index 86a6755..739740d 100644 --- a/index.md +++ b/index.md @@ -32,7 +32,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad - (in German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). -## ADRs in a Nutshell +## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). @@ -42,7 +42,11 @@ A "lightweight" ADR consists of [title, status, context, decision, and consequen We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Any/Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. -## Relation of Nygardian ADRs, MADR, and Other Templates + + +The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. + +The relation of the Nygardian ADR structure, MADR, Y-Statements, and other templates is shown in the following UML class diagram: ```mermaid classDiagram @@ -56,22 +60,20 @@ classDiagram ADR <|-- OtherADRTemplate ``` -## Sustainable Architectural Decisions - -The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. - -## Existing ADR Templates - -Many ADR formats exist, as shown at [@joelparkerhenderson's repository](https://github.com/joelparkerhenderson/architecture_decision_record): +Numerous ADR formats exist, many of which are fearured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record): -- [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`). Lean ADRs to quickly document architectural decisions in code. Slogan: architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). +- [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`) promotes lean ADRs to quickly document architectural decisions close to the code. - [DecisionCapture](https://schubmat.github.io/DecisionCapture/): Templates for agile projects and explanation of the ADR universe, with [example](https://github.com/schubmat/DecisionCapture/blob/master/samples/samples_merged/samples_simpleTemplate_secondSprint.md). - cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. - The [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. +### MADR + +MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contained these four Markdown template files. + ### Y-Statements In short, the Y-statement is as follows: From b50d697cdb81422dc51fac7bc17f4116e552b873 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 15:28:59 +0100 Subject: [PATCH 11/50] Bug fixes, minor edits --- index.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/index.md b/index.md index 739740d..4559624 100644 --- a/index.md +++ b/index.md @@ -42,10 +42,6 @@ A "lightweight" ADR consists of [title, status, context, decision, and consequen We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Any/Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. - - -The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. - The relation of the Nygardian ADR structure, MADR, Y-Statements, and other templates is shown in the following UML class diagram: ```mermaid @@ -60,7 +56,7 @@ classDiagram ADR <|-- OtherADRTemplate ``` -Numerous ADR formats exist, many of which are fearured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record): +Numerous ADR formats exist, many of which are featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record). A few of them are: - [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`) promotes lean ADRs to quickly document architectural decisions close to the code. @@ -72,7 +68,7 @@ A comparison of seven templates can be found in ["Architectural Decision Guidanc ### MADR -MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contained these four Markdown template files. +MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contains these four Markdown template files. ### Y-Statements @@ -139,6 +135,11 @@ For a more detailed list for tooling for MADR, please head to +The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. + +More background information and ADR guidance is available: + - [Architectural Decisions — The Making Of](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) provides a history on architecture decision recording since the late 1990, as well as examples and guidance for provoding decision rationale. - [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) is the blog post by Michael Nygard that popularized the concept. - [Architectural Decision Records (ADR): Open & Transparent Decision History](https://openpracticelibrary.com/practice/architectural-decision-records-adr/) is a practice in the Open Practice Library. @@ -147,6 +148,6 @@ For a more detailed list for tooling for MADR, please head to -More pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). +Additional pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). From 2d95b7b566ac6c3ed95237f7a649fc93d1c58df1 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:19:40 +0100 Subject: [PATCH 12/50] Add spell markdown-linter and spell checker to workspace recommendations --- .vscode/extensions.json | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 082bc94..1cf010b 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,3 +1,7 @@ { - "recommendations": ["ms-vscode-remote.remote-containers"] -} + "recommendations": [ + "davidanson.vscode-markdownlint", + "ltex-plus.vscode-ltex-plus", + "ms-vscode-remote.remote-containers" + ] +} \ No newline at end of file From 916cc3a7ded24bb54a83f22cc32208c6544d5f92 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:38:28 +0100 Subject: [PATCH 13/50] Remove non-needed comments --- index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/index.md b/index.md index 4559624..7ce677a 100644 --- a/index.md +++ b/index.md @@ -19,8 +19,6 @@ The aim of the [GitHub adr organization](https://github.com/adr) is to: 2. Strengthen the tooling around ADRs, in support of agile practices as well as iterative and incremental engineering processes. 3. Provide pointers to public knowledge in the context of AKM and ADRs. - - The repository for the Website of the ADR organization is [https://github.com/adr/adr.github.io](https://github.com/adr/adr.github.io). ## ADRs in the Media @@ -32,7 +30,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad - (in German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). -## ADR Templates +## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). From 93818fa58f405381b54bb5e8acdec66c4c947569 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:39:08 +0100 Subject: [PATCH 14/50] Fix linting issues --- index.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/index.md b/index.md index 7ce677a..8bff27f 100644 --- a/index.md +++ b/index.md @@ -64,11 +64,11 @@ Numerous ADR formats exist, many of which are featured in [@joelparkerhenderson' A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. -### MADR +### MADR MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contains these four Markdown template files. -### Y-Statements +### Y-Statements In short, the Y-statement is as follows: @@ -86,7 +86,6 @@ The long form of it is as follows (extra section "because"): You can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). - ## Decision Capturing Tools *Disclaimer:* @@ -147,5 +146,3 @@ More background information and ADR guidance is available: Additional pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). - - From 638bd267304bfea3675ce2e4a55dc3367bcdb69d Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:44:07 +0100 Subject: [PATCH 15/50] Add note on Markdown --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 805ef25..571b6b8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,6 @@ # Contributing to adr.github.io To improve this page, head to , edit `index.md` or `_tabs/*.md`, and submit a pull request. + +See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling. +The [source](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/_posts/2019-08-08-text-and-typography.md?plain=1) shows the respective Markdown source. From 38662cfaed906b905f9e9f142ca8e85884b2d9c4 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:44:22 +0100 Subject: [PATCH 16/50] Have AD practices the first on the list --- _tabs/ad-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index fe83e76..b2c3c46 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -1,6 +1,6 @@ --- icon: fas fa-check-circle -order: 4 +order: 1 title: AD Practices --- From 4b6165514395cd07d25141f87d20622c2d00daa6 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 15:46:21 +0100 Subject: [PATCH 17/50] Move tooling to `_tabs/adr-tooling.md` --- _tabs/adr-tooling.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ index.md | 44 ---------------------------------------- 2 files changed, 48 insertions(+), 44 deletions(-) create mode 100644 _tabs/adr-tooling.md diff --git a/_tabs/adr-tooling.md b/_tabs/adr-tooling.md new file mode 100644 index 0000000..0abb6e9 --- /dev/null +++ b/_tabs/adr-tooling.md @@ -0,0 +1,48 @@ +--- +icon: fas fa-briefcase +order: 4 +title: Decision Capturing Tools +--- + +> The following list is rather inclusive. +> Please find out about the status and the maturity of the list entries for yourself by following the links. +> We are happy to include more candidate assets here. +{: .prompt-info } + +- [adr-manager](https://adr.github.io/adr-manager/#/): Craft MADR 2.x templates directly in the Web Browser. +- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). + - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) + - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) + - Go rewrite: [adr](https://github.com/marouni/adr) + - Java rewrite: [adr-j](https://github.com/adoble/adr-j) + - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) + - Node.js rewrite: [adr](https://github.com/phodal/adr) + - PHP version: [phpadr](https://github.com/globtec/phpadr) + - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) + - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) + - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) + - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) +- [adr-plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) - plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos. +- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. +- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. +- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). +- [Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. +- [Log4brains](https://github.com/thomvaill/log4brains): CLI and web UI to log and publish your ADRs as a static website. Currently in [low maintenance mode](https://github.com/thomvaill/log4brains/discussions/108#discussioncomment-7607483). +- [Loqbooq](https://loqbooq.app): Web App with Slack integration to record ADR-inspired decision logs +- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. + +For a more detailed list for tooling for MADR, please head to . + +### Tooling related to architecture management + +- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture +- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. +- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). + +### Interesting, but unmaintained tooling + +- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. +- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) +- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. +- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. + diff --git a/index.md b/index.md index 8bff27f..d9edfcb 100644 --- a/index.md +++ b/index.md @@ -86,50 +86,6 @@ The long form of it is as follows (extra section "because"): You can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). -## Decision Capturing Tools - -*Disclaimer:* -The following list is rather inclusive. -Please find out about the status and the maturity of the list entries for yourself by following the links. -We are happy to include more candidate assets here. - -- [adr-manager](https://adr.github.io/adr-manager/#/): Craft MADR 2.x templates directly in the Web Browser. -- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). - - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) - - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) - - Go rewrite: [adr](https://github.com/marouni/adr) - - Java rewrite: [adr-j](https://github.com/adoble/adr-j) - - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) - - Node.js rewrite: [adr](https://github.com/phodal/adr) - - PHP version: [phpadr](https://github.com/globtec/phpadr) - - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) - - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) - - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) - - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) -- [adr-plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) - plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos. -- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. -- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. -- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). -- [Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. -- [Log4brains](https://github.com/thomvaill/log4brains): CLI and web UI to log and publish your ADRs as a static website. Currently in [low maintenance mode](https://github.com/thomvaill/log4brains/discussions/108#discussioncomment-7607483). -- [Loqbooq](https://loqbooq.app): Web App with Slack integration to record ADR-inspired decision logs -- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. - -For a more detailed list for tooling for MADR, please head to . - -### Tooling related to architecture management - -- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture -- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. -- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). - -### Interesting, but unmaintained tooling - -- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. -- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) -- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. -- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. - ## More Information From 79471a45379d2a271347ed695a9d09701c4cf995 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:03:36 +0100 Subject: [PATCH 18/50] Refine adr-tooling --- _tabs/adr-tooling.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/_tabs/adr-tooling.md b/_tabs/adr-tooling.md index 0abb6e9..057f87d 100644 --- a/_tabs/adr-tooling.md +++ b/_tabs/adr-tooling.md @@ -4,12 +4,32 @@ order: 4 title: Decision Capturing Tools --- -> The following list is rather inclusive. +> The following lists are rather inclusive and sorted alphabetically. > Please find out about the status and the maturity of the list entries for yourself by following the links. > We are happy to include more candidate assets here. {: .prompt-info } -- [adr-manager](https://adr.github.io/adr-manager/#/): Craft MADR 2.x templates directly in the Web Browser. +## Tooling to create and maintain decision files + +### Any template + +- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). + +### MADR template + +| Name | MADR Version | Comment | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | +| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | +| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | +| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | +| [eADR](https://github.com/adr/e-adr) | 1.0.0 | Embed decisions in Java code as annotations (`@MADR(...)`) | +| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | +| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | +| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | + +### Nygard template + - [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) @@ -22,27 +42,24 @@ title: Decision Capturing Tools - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) -- [adr-plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) - plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos. - [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. - [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. -- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). -- [Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. -- [Log4brains](https://github.com/thomvaill/log4brains): CLI and web UI to log and publish your ADRs as a static website. Currently in [low maintenance mode](https://github.com/thomvaill/log4brains/discussions/108#discussioncomment-7607483). -- [Loqbooq](https://loqbooq.app): Web App with Slack integration to record ADR-inspired decision logs +- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs - [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. -For a more detailed list for tooling for MADR, please head to . +## Tooling close to the code -### Tooling related to architecture management +- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. + +## Tooling related to architecture management - [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture - [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. - [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). -### Interesting, but unmaintained tooling +## Interesting, but unmaintained tooling - [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. - [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) - [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. - [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. - From 235ee2872e095eea1aea3ac001a7a3db23ee9e5b Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:06:31 +0100 Subject: [PATCH 19/50] Introduce "general" as filler word --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index d9edfcb..b3519b6 100644 --- a/index.md +++ b/index.md @@ -91,7 +91,7 @@ You can find more explanations and examples on Medium: [Y-Statements - A Light T The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. -More background information and ADR guidance is available: +More general background information and ADR guidance is available: - [Architectural Decisions — The Making Of](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) provides a history on architecture decision recording since the late 1990, as well as examples and guidance for provoding decision rationale. - [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) is the blog post by Michael Nygard that popularized the concept. From e1fca8815d8d8d7ad06af56a0de65ff293ffdbde Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:06:49 +0100 Subject: [PATCH 20/50] Keep paragraph together (and remove "Any/" from MADR name) --- index.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/index.md b/index.md index b3519b6..a2efc01 100644 --- a/index.md +++ b/index.md @@ -33,12 +33,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). - - - -We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Any/Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. +We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. The relation of the Nygardian ADR structure, MADR, Y-Statements, and other templates is shown in the following UML class diagram: From 2bb5c4b9e3606224acfc2c1bd379fa6ff588b728 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:20:43 +0100 Subject: [PATCH 21/50] Remove unmaintained Decision Caputure --- index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/index.md b/index.md index a2efc01..f0af009 100644 --- a/index.md +++ b/index.md @@ -53,7 +53,6 @@ Numerous ADR formats exist, many of which are featured in [@joelparkerhenderson' - [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`) promotes lean ADRs to quickly document architectural decisions close to the code. -- [DecisionCapture](https://schubmat.github.io/DecisionCapture/): Templates for agile projects and explanation of the ADR universe, with [example](https://github.com/schubmat/DecisionCapture/blob/master/samples/samples_merged/samples_simpleTemplate_secondSprint.md). - cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. - The [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. From 7aaf019a4c5cffe2680cd8b5c5e64c68ab93a9c0 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:22:01 +0100 Subject: [PATCH 22/50] Reorder UML diagram to follow structure of sentence above --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index f0af009..cf8354e 100644 --- a/index.md +++ b/index.md @@ -43,9 +43,9 @@ classDiagram class ADR { <> } + ADR <|-- NygardADR ADR <|-- MADR ADR <|-- Y-Statement - ADR <|-- NygardADR ADR <|-- OtherADRTemplate ``` From 6e15de945f9e9bbc7d76744190929d003a239b8c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:25:38 +0100 Subject: [PATCH 23/50] Move content "Numberous ADR formats" to more appropriate places --- index.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/index.md b/index.md index cf8354e..7f5d237 100644 --- a/index.md +++ b/index.md @@ -49,15 +49,6 @@ classDiagram ADR <|-- OtherADRTemplate ``` -Numerous ADR formats exist, many of which are featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record). A few of them are: - - -- [MADR](https://adr.github.io/madr/): The Markdown Architecture Decision Records (MADR: `[ˈmæɾɚ]`) promotes lean ADRs to quickly document architectural decisions close to the code. -- cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. -- The [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. - -A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. - ### MADR MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contains these four Markdown template files. @@ -78,7 +69,13 @@ The long form of it is as follows (extra section "because"): > accepting ``, > because ``. -You can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). +cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. +Finally, you can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). + +### Other templates + +Numerous other ADR formats exist, many of which are featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record). +Moreover, there is the [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. ## More Information @@ -87,6 +84,7 @@ The work in the adr organization is based on the guidelines and principles in [S More general background information and ADR guidance is available: +- A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. - [Architectural Decisions — The Making Of](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) provides a history on architecture decision recording since the late 1990, as well as examples and guidance for provoding decision rationale. - [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) is the blog post by Michael Nygard that popularized the concept. - [Architectural Decision Records (ADR): Open & Transparent Decision History](https://openpracticelibrary.com/practice/architectural-decision-records-adr/) is a practice in the Open Practice Library. From 9d10b1e81174865c8e5b5e268797bc464b9fce26 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:29:35 +0100 Subject: [PATCH 24/50] eADR is in other section - removed from table --- _tabs/adr-tooling.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_tabs/adr-tooling.md b/_tabs/adr-tooling.md index 057f87d..65e1e3b 100644 --- a/_tabs/adr-tooling.md +++ b/_tabs/adr-tooling.md @@ -23,7 +23,6 @@ title: Decision Capturing Tools | [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | | [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | | [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | -| [eADR](https://github.com/adr/e-adr) | 1.0.0 | Embed decisions in Java code as annotations (`@MADR(...)`) | | [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | | [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | | [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | From b06552acf28cffc41ec4e79278219caad6fed213 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 16:33:19 +0100 Subject: [PATCH 25/50] More deep links for MADR --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 7f5d237..b671672 100644 --- a/index.md +++ b/index.md @@ -51,7 +51,7 @@ classDiagram ### MADR -MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. The [template folder](https://github.com/adr/madr/tree/4.0.0/template) of the MADR repository contains these four Markdown template files. +MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a [full](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md?plain=1) and a [minimal template](https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1), both of which now come in an [annotated and a bare format](https://github.com/adr/madr/tree/4.0.0/template#decisions). ### Y-Statements From cd85fa940c7076c8d85d02e974fd0ffcb2ded729 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 17:21:51 +0100 Subject: [PATCH 26/50] Consistency edits, wording fix in templates section of main page --- index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/index.md b/index.md index b671672..6f1b714 100644 --- a/index.md +++ b/index.md @@ -51,9 +51,9 @@ classDiagram ### MADR -MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a [full](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md?plain=1) and a [minimal template](https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1), both of which now come in an [annotated and a bare format](https://github.com/adr/madr/tree/4.0.0/template#decisions). +MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a [full](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md?plain=1) and a [minimal](https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1) template, both of which now come in an annotated and a bare format. Rationale for this decision is available [here](https://github.com/adr/madr/tree/4.0.0/template#decisions). -### Y-Statements +### Y-Statement In short, the Y-statement is as follows: @@ -72,10 +72,11 @@ The long form of it is as follows (extra section "because"): cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information. Finally, you can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177). -### Other templates +### Other ADR templates Numerous other ADR formats exist, many of which are featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record). -Moreover, there is the [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. + +Moreover, [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. ## More Information From bbaacbf71bdf417bc96686e53ae91425a10d5c99 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 17:23:00 +0100 Subject: [PATCH 27/50] MADR first in text and UML --- index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.md b/index.md index 6f1b714..b642d7a 100644 --- a/index.md +++ b/index.md @@ -35,7 +35,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. -The relation of the Nygardian ADR structure, MADR, Y-Statements, and other templates is shown in the following UML class diagram: +The relation of the MADR, Nygardian ADR structure, Y-Statements, and other templates is shown in the following UML class diagram: ```mermaid classDiagram @@ -43,8 +43,8 @@ classDiagram class ADR { <> } - ADR <|-- NygardADR ADR <|-- MADR + ADR <|-- NygardADR ADR <|-- Y-Statement ADR <|-- OtherADRTemplate ``` From 2e97fa0b5a09c5753491b1fa7df7099ac8f51472 Mon Sep 17 00:00:00 2001 From: Olaf Zimmermann Date: Mon, 28 Oct 2024 17:24:17 +0100 Subject: [PATCH 28/50] Typo, year of Nygard post --- index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.md b/index.md index b642d7a..9f11392 100644 --- a/index.md +++ b/index.md @@ -86,8 +86,8 @@ The work in the adr organization is based on the guidelines and principles in [S More general background information and ADR guidance is available: - A comparison of seven templates can be found in ["Architectural Decision Guidance Across Projects --- Problem Space Modeling, Decision Backlog Management and Cloud Computing Knowledge"](https://www.ost.ch/fileadmin/dateiliste/3_forschung_dienstleistung/institute/ifs/cloud-application-lab/admentor-wicsa2015ubmissionv11nc.pdf), a WICSA 2015 conference paper. -- [Architectural Decisions — The Making Of](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) provides a history on architecture decision recording since the late 1990, as well as examples and guidance for provoding decision rationale. -- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) is the blog post by Michael Nygard that popularized the concept. +- [Architectural Decisions — The Making Of](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html) provides a history on architecture decision recording since the late 1990, as well as examples and guidance for providing decision rationale. +- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) is the blog post from 2011 by Michael Nygard that popularized the concept. - [Architectural Decision Records (ADR): Open & Transparent Decision History](https://openpracticelibrary.com/practice/architectural-decision-records-adr/) is a practice in the Open Practice Library. - An AWS Prescriptive Guidance recommends [using architectural decision records to streamline technical decision-making for a software development project](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html). - [Architecture Decision Records in Action by Michael Keeling (IBM Watson Group) and Joe Runde (IBM) [YouTube]](https://www.youtube.com/watch?v=41NVge3_cYo) is a presentation that includes empirical numbers. From 09fb28324e0e96b7c2b62a42e23b7d81ad5ff1f2 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:47:12 +0100 Subject: [PATCH 29/50] Use information box --- _tabs/ad-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index b2c3c46..60f0d0c 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -4,8 +4,8 @@ order: 1 title: AD Practices --- -*Disclaimer:* -The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. +> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. +{: .prompt-info } [Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. From 87a59b064676f7016a9b1aeb8a44d1248a7b6089 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:47:41 +0100 Subject: [PATCH 30/50] Fix linting issue --- _tabs/ad-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 60f0d0c..9f1341c 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -30,7 +30,7 @@ The [Design Practice Repository](https://socadk.github.io/design-practice-reposi Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). -### Third-party articles +### Third-party articles - [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser - More will be featured in future versions of this page, suggestions are welcome! From 5eda12a060564f8a4cc4c2d95d4711bbe17b9808 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:51:18 +0100 Subject: [PATCH 31/50] Swap Y-Statement and Nygard --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 9f11392..ff897f0 100644 --- a/index.md +++ b/index.md @@ -44,8 +44,8 @@ classDiagram <> } ADR <|-- MADR - ADR <|-- NygardADR ADR <|-- Y-Statement + ADR <|-- NygardADR ADR <|-- OtherADRTemplate ``` From cb3bf1042d29dd9b7b20571ebf5bf1a139e309bf Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:53:07 +0100 Subject: [PATCH 32/50] Emphasize "considered options" --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index ff897f0..34dbc64 100644 --- a/index.md +++ b/index.md @@ -33,7 +33,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). -We think that the considered options with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. +We think that the _considered options_ with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. The relation of the MADR, Nygardian ADR structure, Y-Statements, and other templates is shown in the following UML class diagram: From 9540df380f1ef72afa346f46a62ecf1e78004297 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:54:31 +0100 Subject: [PATCH 33/50] Remove MADR pronouncation and add example for meta data --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 34dbc64..e3f91c8 100644 --- a/index.md +++ b/index.md @@ -33,7 +33,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). -We think that the _considered options_ with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR, pronounced `[ˈmæɾɚ]`) project, located in the adr organization at GitHub, includes such tradeoff analysis information. It also adds additional metadata. +We think that the _considered options_ with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR) projec includes such tradeoff analysis information. It also adds additional metadata such as decision makers and confirmation. The relation of the MADR, Nygardian ADR structure, Y-Statements, and other templates is shown in the following UML class diagram: From 4cee6e6fad28346325925f3925237664c782123b Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:54:52 +0100 Subject: [PATCH 34/50] Remove obsole3te linting command --- index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/index.md b/index.md index e3f91c8..b22ab04 100644 --- a/index.md +++ b/index.md @@ -29,7 +29,6 @@ The repository for the Website of the ADR organization is [https://github.com/ad - Chapter 3 of ["Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges"](https://api-patterns.org/book/) in the Addison Wesley Signature Series at Pearson features six narratives guiding through the conceptual level of API design: 29 recurring decisions with options and criteria. Learn more in this [blog post](https://medium.com/nerd-for-tech/api-patterns-website-redesigned-and-sample-book-chapter-available-df9daf4b5e15). - (in German) [Gut dokumentiert: Architecture Decision Records](https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html) by [@obfischer](https://github.com/obfischer) published at [heise online](https://www.heise.de/). - ## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). From 5c4aa90793b96978a12e02f0c43ca262dec59d03 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:55:43 +0100 Subject: [PATCH 35/50] Fix linting issue. --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index b22ab04..c04ccd9 100644 --- a/index.md +++ b/index.md @@ -80,7 +80,7 @@ Moreover, [42010 architecture description (AD) template](http://www.iso-architec ## More Information -The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. +The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. More general background information and ADR guidance is available: From ac18e95c81f9cd5253f9f32f4ba71871fb5930f5 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 18:55:48 +0100 Subject: [PATCH 36/50] Fixup --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index c04ccd9..cbbaa6b 100644 --- a/index.md +++ b/index.md @@ -32,7 +32,7 @@ The repository for the Website of the ADR organization is [https://github.com/ad ## ADR Templates A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). -We think that the _considered options_ with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR) projec includes such tradeoff analysis information. It also adds additional metadata such as decision makers and confirmation. +We think that the *considered options* with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR) projec includes such tradeoff analysis information. It also adds additional metadata such as decision makers and confirmation. The relation of the MADR, Nygardian ADR structure, Y-Statements, and other templates is shown in the following UML class diagram: From 15d1e8d00f53f34516eb85a5a69c6d3800d6cb0d Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 19:02:05 +0100 Subject: [PATCH 37/50] Mave additional resources as bullet point (for consistent layout) --- index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.md b/index.md index cbbaa6b..3d0dd62 100644 --- a/index.md +++ b/index.md @@ -92,5 +92,4 @@ More general background information and ADR guidance is available: - [Architecture Decision Records in Action by Michael Keeling (IBM Watson Group) and Joe Runde (IBM) [YouTube]](https://www.youtube.com/watch?v=41NVge3_cYo) is a presentation that includes empirical numbers. - [ADRs and Architecture Stories](https://www.developertoarchitect.com/lessons/lesson168.html) is part of a video series by Mark Richards explaining ADRs, starting from Nygard's template. - -Additional pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). +- Additional pointers and resources can be found on the web page [Architectural Knowledge Management (AKM)](https://www.ost.ch/en/research-and-consulting-services/computer-science/ifs-institute-for-software-new/cloud-application-lab/architectural-knowledge-management-akm). From 0348caa3a21bbd23e7fd0f73b9b0229f54f02b8a Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 19:02:24 +0100 Subject: [PATCH 38/50] Mak eheading more pleasent (hopefully) --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 3d0dd62..c052803 100644 --- a/index.md +++ b/index.md @@ -77,7 +77,7 @@ Numerous other ADR formats exist, many of which are featured in [@joelparkerhend Moreover, [42010 architecture description (AD) template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions. -## More Information +## Background Information The work in the adr organization is based on the guidelines and principles in [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) by Zdun et al., for instance the Y-statement format suggested in that article. From 53d182624a2c52e724760c72732ad775bbd6bf72 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 21:09:13 +0100 Subject: [PATCH 39/50] Convert to "blog" posts --- CONTRIBUTING.md | 2 +- _config.yml | 6 +-- _data/share.yml | 50 ++++++++------------- index.md => _posts/2024-10-26-adrs.md | 8 ++-- _posts/2024-10-27-ad-practices.md | 40 +++++++++++++++++ _posts/2024-10-28-adr-tooling.md | 63 +++++++++++++++++++++++++++ _tabs/ad-practices.md | 38 +--------------- _tabs/adr-tooling.md | 61 +------------------------- _tabs/adrs.md | 5 +++ index.html | 4 ++ 10 files changed, 140 insertions(+), 137 deletions(-) rename index.md => _posts/2024-10-26-adrs.md (97%) create mode 100644 _posts/2024-10-27-ad-practices.md create mode 100644 _posts/2024-10-28-adr-tooling.md create mode 100644 _tabs/adrs.md create mode 100644 index.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 571b6b8..40ca9d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to adr.github.io -To improve this page, head to , edit `index.md` or `_tabs/*.md`, and submit a pull request. +To improve this page, head to , edit `_posts/*.md`, and submit a pull request. See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling. The [source](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/_posts/2019-08-08-text-and-typography.md?plain=1) shows the respective Markdown source. diff --git a/_config.yml b/_config.yml index b9e8c42..2a38266 100644 --- a/_config.yml +++ b/_config.yml @@ -150,7 +150,7 @@ pwa: deny_paths: # - "/example" # URLs match `/example/*` will not be cached by the PWA -# paginate: 10 +paginate: 10 # The base URL of your site baseurl: "" @@ -171,7 +171,7 @@ kramdown: collections: tabs: - output: true + output: false sort_by: order defaults: @@ -184,7 +184,7 @@ defaults: toc: true # Display TOC column in posts. # DO NOT modify the following parameter unless you are confident enough # to update the code of all other post links in this project. - permalink: /posts/:title/ + permalink: :title/ - scope: path: _drafts values: diff --git a/_data/share.yml b/_data/share.yml index 6f97568..b2ff94a 100644 --- a/_data/share.yml +++ b/_data/share.yml @@ -2,48 +2,36 @@ # Icons from platforms: - - type: Twitter - icon: "fa-brands fa-square-x-twitter" - link: "https://twitter.com/intent/tweet?text=TITLE&url=URL" - - - type: Facebook - icon: "fab fa-facebook-square" - link: "https://www.facebook.com/sharer/sharer.php?title=TITLE&u=URL" - - - type: Telegram - icon: "fab fa-telegram" - link: "https://t.me/share/url?url=URL&text=TITLE" - # Uncomment below if you need to. # - # - type: Linkedin - # icon: "fab fa-linkedin" - # link: "https://www.linkedin.com/sharing/share-offsite/?url=URL" + - type: Linkedin + icon: "fab fa-linkedin" + link: "https://www.linkedin.com/sharing/share-offsite/?url=URL" # # - type: Weibo # icon: "fab fa-weibo" # link: "https://service.weibo.com/share/share.php?title=TITLE&url=URL" # - # - type: Mastodon - # icon: "fa-brands fa-mastodon" - # # See: https://github.com/justinribeiro/share-to-mastodon#properties - # instances: - # - label: mastodon.social - # link: "https://mastodon.social/" - # - label: mastodon.online - # link: "https://mastodon.online/" - # - label: fosstodon.org - # link: "https://fosstodon.org/" + - type: Mastodon + icon: "fa-brands fa-mastodon" + # # See: https://github.com/justinribeiro/share-to-mastodon#properties + instances: + # - label: mastodon.social + # link: "https://mastodon.social/" + # - label: mastodon.online + # link: "https://mastodon.online/" + - label: fosstodon.org + link: "https://fosstodon.org/" # - label: photog.social # link: "https://photog.social/" # - # - type: Bluesky - # icon: "fa-brands fa-bluesky" - # link: "https://bsky.app/intent/compose?text=TITLE%20URL" + - type: Bluesky + icon: "fa-brands fa-bluesky" + link: "https://bsky.app/intent/compose?text=TITLE%20URL" # - # - type: Reddit - # icon: "fa-brands fa-square-reddit" - # link: "https://www.reddit.com/submit?url=URL&title=TITLE" + - type: Reddit + icon: "fa-brands fa-square-reddit" + link: "https://www.reddit.com/submit?url=URL&title=TITLE" # # - type: Threads # icon: "fa-brands fa-square-threads" diff --git a/index.md b/_posts/2024-10-26-adrs.md similarity index 97% rename from index.md rename to _posts/2024-10-26-adrs.md index c052803..627926e 100644 --- a/index.md +++ b/_posts/2024-10-26-adrs.md @@ -1,10 +1,10 @@ --- -layout: default +title: Architectural Decision Records (ADRs) +pin: true mermaid: true +toc: true --- -# Architectural Decision Records (ADRs) - ## Motivation and Definitions An [Architectural Decision (AD)](https://en.wikipedia.org/wiki/Architectural_decision) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. @@ -19,8 +19,6 @@ The aim of the [GitHub adr organization](https://github.com/adr) is to: 2. Strengthen the tooling around ADRs, in support of agile practices as well as iterative and incremental engineering processes. 3. Provide pointers to public knowledge in the context of AKM and ADRs. -The repository for the Website of the ADR organization is [https://github.com/adr/adr.github.io](https://github.com/adr/adr.github.io). - ## ADRs in the Media - The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) at Microsoft Ignite features ADRs and this website (10/11/2024). diff --git a/_posts/2024-10-27-ad-practices.md b/_posts/2024-10-27-ad-practices.md new file mode 100644 index 0000000..c8d8e66 --- /dev/null +++ b/_posts/2024-10-27-ad-practices.md @@ -0,0 +1,40 @@ +--- +title: AD Practices +toc: true +--- + +> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. +{: .prompt-info } + +[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. + +## AD Making + +The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. + +[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. + +## Good ADRs --- and How to Get to Them + +### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: + +1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. +2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) +3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. +4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) +5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. +6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). +7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list +8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) + +Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). + +### Third-party articles + +- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser +- More will be featured in future versions of this page, suggestions are welcome! +- *to be continued* + +## From Architectural Decisions to Design/Any Decisions + +[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. diff --git a/_posts/2024-10-28-adr-tooling.md b/_posts/2024-10-28-adr-tooling.md new file mode 100644 index 0000000..b1f3a7c --- /dev/null +++ b/_posts/2024-10-28-adr-tooling.md @@ -0,0 +1,63 @@ +--- +title: Decision Capturing Tools +toc: true +--- + +> The following lists are rather inclusive and sorted alphabetically. +> Please find out about the status and the maturity of the list entries for yourself by following the links. +> We are happy to include more candidate assets here. +{: .prompt-info } + +## Tooling to create and maintain decision files + +### Any template + +- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). + +### MADR template + +| Name | MADR Version | Comment | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | +| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | +| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | +| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | +| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | +| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | +| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | + +### Nygard template + +- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). + - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) + - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) + - Go rewrite: [adr](https://github.com/marouni/adr) + - Java rewrite: [adr-j](https://github.com/adoble/adr-j) + - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) + - Node.js rewrite: [adr](https://github.com/phodal/adr) + - PHP version: [phpadr](https://github.com/globtec/phpadr) + - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) + - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) + - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) + - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) +- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. +- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. +- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs +- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. + +## Tooling close to the code + +- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. + +## Tooling related to architecture management + +- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture +- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. +- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). + +## Interesting, but unmaintained tooling + +- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. +- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) +- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. +- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. diff --git a/_tabs/ad-practices.md b/_tabs/ad-practices.md index 9f1341c..04cadf7 100644 --- a/_tabs/ad-practices.md +++ b/_tabs/ad-practices.md @@ -1,41 +1,5 @@ --- icon: fas fa-check-circle -order: 1 +order: 2 title: AD Practices --- - -> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them. -{: .prompt-info } - -[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page. - -## AD Making - -The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR. - -[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions. - -## Good ADRs --- and How to Get to Them - -### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template: - -1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START. -2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html) -3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns. -4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) -5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*. -6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html). -7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list -8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html) - -Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr). - -### Third-party articles - -- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser -- More will be featured in future versions of this page, suggestions are welcome! -- *to be continued* - -## From Architectural Decisions to Design/Any Decisions - -[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs. diff --git a/_tabs/adr-tooling.md b/_tabs/adr-tooling.md index 65e1e3b..5781307 100644 --- a/_tabs/adr-tooling.md +++ b/_tabs/adr-tooling.md @@ -1,64 +1,5 @@ --- icon: fas fa-briefcase -order: 4 +order: 3 title: Decision Capturing Tools --- - -> The following lists are rather inclusive and sorted alphabetically. -> Please find out about the status and the maturity of the list entries for yourself by following the links. -> We are happy to include more candidate assets here. -{: .prompt-info } - -## Tooling to create and maintain decision files - -### Any template - -- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR). - -### MADR template - -| Name | MADR Version | Comment | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs | -| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way | -| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension | -| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos | -| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs | -| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. | -| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) | - -### Nygard template - -- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md). - - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools) - - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli) - - Go rewrite: [adr](https://github.com/marouni/adr) - - Java rewrite: [adr-j](https://github.com/adoble/adr-j) - - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools) - - Node.js rewrite: [adr](https://github.com/phodal/adr) - - PHP version: [phpadr](https://github.com/globtec/phpadr) - - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps) - - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/) - - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords) - - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs) -- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs. -- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes. -- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs -- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types. - -## Tooling close to the code - -- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations. - -## Tooling related to architecture management - -- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture -- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation. -- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/). - -## Interesting, but unmaintained tooling - -- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs. -- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/) -- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions. -- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others. diff --git a/_tabs/adrs.md b/_tabs/adrs.md new file mode 100644 index 0000000..b8e00d9 --- /dev/null +++ b/_tabs/adrs.md @@ -0,0 +1,5 @@ +--- +icon: fas fa-info +order: 1 +title: About ADRs +--- diff --git a/index.html b/index.html new file mode 100644 index 0000000..1357b08 --- /dev/null +++ b/index.html @@ -0,0 +1,4 @@ +--- +layout: home +# Index page +--- From c8f8c3d9dd21f0372d7214017cf88be872a44db4 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Mon, 28 Oct 2024 21:33:04 +0100 Subject: [PATCH 40/50] Make "ADR Templates" a sub page --- _posts/2024-10-25-adr-templates.md | 52 ++++++++++++++++++++++++++++++ _posts/2024-10-26-adrs.md | 49 ---------------------------- _tabs/adr-templates.md | 5 +++ _tabs/adr-tooling.md | 2 +- 4 files changed, 58 insertions(+), 50 deletions(-) create mode 100644 _posts/2024-10-25-adr-templates.md create mode 100644 _tabs/adr-templates.md diff --git a/_posts/2024-10-25-adr-templates.md b/_posts/2024-10-25-adr-templates.md new file mode 100644 index 0000000..637e995 --- /dev/null +++ b/_posts/2024-10-25-adr-templates.md @@ -0,0 +1,52 @@ +--- +title: ADR Templates +pin: true +mermaid: true +toc: true +--- + +A "lightweight" ADR consists of [title, status, context, decision, and consequences](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) according to [@mtnygard](https://github.com/mtnygard). +We think that the *considered options* with their pros and cons are also crucial to understand the reason of a chosen option. [MADR](https://adr.github.io/madr/). Therefore, the Markdown Architectural Decision Records (MADR) projec includes such tradeoff analysis information. It also adds additional metadata such as decision makers and confirmation. + +The relation of the MADR, Nygardian ADR structure, Y-Statements, and other templates is shown in the following UML class diagram: + +```mermaid +classDiagram + direction TB + class ADR { + <> + } + ADR <|-- MADR + ADR <|-- Y-Statement + ADR <|-- NygardADR + ADR <|-- OtherADRTemplate +``` + +### MADR + +MADR is about architectural decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). The project provides a [full](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md?plain=1) and a [minimal](https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1) template, both of which now come in an annotated and a bare format. Rationale for this decision is available [here](https://github.com/adr/madr/tree/4.0.0/template#decisions). + +### Y-Statement + +In short, the Y-statement is as follows: + +> In the context of ``, facing `` we decided for `