Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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/

Slide 5

Slide 5 text

5 MADRs in JabRef

Slide 6

Slide 6 text

6 Example MADR

Slide 7

Slide 7 text

7 Example MADR (part 2)

Slide 8

Slide 8 text

8 Discussion: Should it get closer to the code?

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

10 What to do in a new project?

Slide 11

Slide 11 text

11 Example MADR in JabRef

Slide 12

Slide 12 text

12 Example MADR in Eclipse Winery

Slide 13

Slide 13 text

13 Markdown Architectural Decision Records MADR

Slide 14

Slide 14 text

14 Generalizing MADR

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

17 Existing GADRs

Slide 18

Slide 18 text

18 Tooling GADR JabRef Eclipse Winery

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

22 Background

Slide 23

Slide 23 text

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).

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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