diff --git a/_posts/2024-10-25-adr-templates.md b/_posts/2024-10-25-adr-templates.md index 069a572..d4ea19f 100644 --- a/_posts/2024-10-25-adr-templates.md +++ b/_posts/2024-10-25-adr-templates.md @@ -25,21 +25,21 @@ classDiagram ADR <|-- OtherADRTemplate ``` -### Markdown Architectural Decision Records (MADR) +## Markdown Architectural Decision Records (MADR) -MADR is about architectural decisions that *matter* ([`[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation)). You can read more about MADR [here](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html). You can use MADR without installing software by populating the template in any text editor. Additionally, a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager) is available, though it may be outdated and lack support for the latest features. [Other tools](https://adr.github.io/adr-tooling/#madr-template) are also available. +MADR is about architectural decisions that *matter* ([`[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation)). Olaf Zimmermann's [MADR Template Primer](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html) covers it in more depth. You can use MADR without installing software by populating the template in any text editor. Additionally, a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager) is available, though it may be outdated and lack support for the latest features. [Other tools](https://adr.github.io/adr-tooling/#madr-template) are also available. -MADR 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). +MADR 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. The rationale for this decision is documented in the [template decisions](https://github.com/adr/madr/tree/4.0.0/template#decisions). We think that the *considered options* with their pros and cons are crucial to understand the reasons for choosing a particular design. Therefore, the [Markdown Architectural Decision Records (MADR)](https://adr.github.io/madr/) project in this organization includes such tradeoff analysis information. It also suggests metadata such as decision makers and confirmation in addition to decision status. -### Nygard ADR +## Nygard ADR An ADR consists of title, status, context, decision, and consequences according to "Documenting Architecture Decisions" by [@mtnygard](https://github.com/mtnygard). -The blog post from 2011 that suggests this structure is [here](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) and a Markdown rendering of it is available [here](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md). +The original [blog post from 2011](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) suggests this structure, and a [Markdown rendering](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md) is also available. -### Y-Statement +## Y-Statement In short, the Y-statement is as follows: @@ -58,7 +58,7 @@ 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 ADR templates +## Other ADR templates Numerous other ADR formats exist, many of which are also featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record). diff --git a/assets/2026-03-10 - ADR, MADR, eADR - JavaLand 2026.pdf b/assets/2026-03-10 - ADR, MADR, eADR - JavaLand 2026.pdf new file mode 100644 index 0000000..e64be8e Binary files /dev/null and b/assets/2026-03-10 - ADR, MADR, eADR - JavaLand 2026.pdf differ diff --git a/index.md b/index.md index 3406827..acbc844 100644 --- a/index.md +++ b/index.md @@ -21,7 +21,8 @@ The aim of the [GitHub adr organization](https://github.com/adr) is to: ## ADRs in the Media -- The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) features ADRs and this website (10/11/2024). +- (in German) [Architekturentscheidungen sichtbar und nachvollziehbar gestalten](assets/2026-03-10%20-%20ADR%2C%20MADR%2C%20eADR%20-%20JavaLand%202026.pdf) at [JavaLand 2026](https://www.javaland.eu/) (2026-03-10). +- The [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record) features ADRs and this website (2024-11-10). - [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).