Markdown ArchitecturalDecisionRecords: Capturing Decisions Where the Developer is Working

1e6ae94f84a34641ccc5abc86a664694?s=47 Oliver Kopp
September 29, 2020

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.

1e6ae94f84a34641ccc5abc86a664694?s=128

Oliver Kopp

September 29, 2020
Tweet

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