Research Dr. Oliver Kopp JabRef e.V. @koppor Markdown Architectural Decision Records: Capturing Decisions Where the Developer is Working https://adr.github.io/madr/ Keynote at the Workshop “Second Software Documentation Generation Challenge (DocGen2)” https://dysdoc.github.io/docgen2/index.html

2 Architectural Decisions  “Let us use Angular and Spring for our Web App because everybody else does, it will look good on our CVs.”  “We chose GSON as our JSON Java parser because of its superior performance shown in PoCand the active community support for it.”  G. Booch: “Architectural decisions are the design decisions that are costly to change” More information https://speakerdeck.com/vanto/a-brief-introduction-to-architectural-decision-records

3 ThoughtWorks thinks… https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records

4 MADR (minimal) # [short title of solved problem and solution] ## Context and Problem Statement [Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] ## Considered Options * [option 1] * [option 2] * [option 3] ## Decision Outcome Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. Full MADR: https://adr.github.io/madr/

5 MADRs in JabRef

6 Example MADR

7 Example MADR (part 2)

8 Discussion: Should it get closer to the code?

9 Discussion: Closer to the Code? Embedded Architectural Decision Records https://adr.github.io/e-adr/

10 What to do in a new project?

11 Example MADR in JabRef

12 Example MADR in Eclipse Winery

13 Markdown Architectural Decision Records MADR

14 Generalizing MADR

15 Problem Space and Solution Space Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015

16 Process Around Creation Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015

17 Existing GADRs

18 Tooling GADR JabRef Eclipse Winery

19 Tooling https://snisnisniksonah.github.io/gadr-demo/test.html

20 Missing Tooling: AD-Mentor in the Web Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015

21 Conclusion and Outlook  MADR as lightweight decision record format  GADR as knowledge capturing format  GitHub Pull Request Check  Is an ADR referenced?  Better Tooling for Governance (AD Mentor in the Web)  Definition of a process  Collection of GADRs  https://adr.github.io/gadr/ @koppor

22 Background

23 Y-Statement In the context of , facing we decided for and neglected , to achieve , accepting , because . U. Zdun, R. Capilla, H. Tran, O. Zimmermann, Sustainable Architectural Design Decisions, IEEE Software, Volume 30, Number 6 (2013).

24 Michael Nygard’s Lightweight Decision Record # NUMBER. TITLE Date: DATE ## Status STATUS ## Context The issue motivating this decision, and any context that influences or constrains the decision. ## Decision The change that we're proposing or have agreed to implement. ## Consequences What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated. More markdown-based records: https://github.com/joelparkerhenderson/architecture_decision_record

25 Overview on existing templates Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015