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
   

   View Slide

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
   

   View Slide

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

   View Slide

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/
   

   View Slide

5. 5
   MADRs in JabRef
   

   View Slide

6. 6
   Example MADR
   

   View Slide

7. 7
   Example MADR (part 2)
   

   View Slide

8. 8
   Discussion: Should it get closer to the code?
   

   View Slide

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

   View Slide

10. 10
    What to do in a new project?
    

    View Slide

11. 11
    Example MADR in JabRef
    

    View Slide

12. 12
    Example MADR in Eclipse Winery
    

    View Slide

13. 13
    Markdown Architectural Decision Records
    MADR
    

    View Slide

14. 14
    Generalizing MADR
    

    View Slide

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

    View Slide

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

    View Slide

17. 17
    Existing GADRs
    

    View Slide

18. 18
    Tooling
    GADR
    JabRef
    Eclipse Winery
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

22. 22
    Background
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide