Markdown ArchitecturalDecisionRecords: Capturing Decisions Where the Developer is Working

Keynote at the Second Software Documentation Generation Challenge (DocGen2) Workshop

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo). It should be as easy as possible to a) write down the decisions and b) to version the decisions. “Markdown and Architectural Decision Records” are one way to fulfill these requirements. This talk outlines MADR, presents its current use and outlines next research and development steps.

Transcript

1. 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. 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. 3 ThoughtWorks thinks… https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
4. 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. 5 MADRs in JabRef
6. 6 Example MADR
7. 7 Example MADR (part 2)
8. 8 Discussion: Should it get closer to the code?
9. 9 Discussion: Closer to the Code? Embedded Architectural Decision Records https://adr.github.io/e-adr/
10. 10 What to do in a new project?
11. 11 Example MADR in JabRef
12. 12 Example MADR in Eclipse Winery
13. 13 Markdown Architectural Decision Records MADR
14. 14 Generalizing MADR
15. 15 Problem Space and Solution Space Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015
16. 16 Process Around Creation Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015
17. 17 Existing GADRs
18. 18 Tooling GADR JabRef Eclipse Winery
19. 19 Tooling https://snisnisniksonah.github.io/gadr-demo/test.html
20. 20 Missing Tooling: AD-Mentor in the Web Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015
21. 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. 22 Background
23. 23 Y-Statement In the context of <use case/user story u>, facing <concern c> we decided for <option o> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside / undesired consequences>, because <additional rationale>. U. Zdun, R. Capilla, H. Tran, O. Zimmermann, Sustainable Architectural Design Decisions, IEEE Software, Volume 30, Number 6 (2013).
24. 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. 25 Overview on existing templates Source: Olaf Zimmermann et al.: Architectural Decision Guidance across Projects, WICSA 2015