Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Better software architecture documentation with Domain-driven Design

Better software architecture documentation with Domain-driven Design

Michael Plöd

January 27, 2021
Tweet

More Decks by Michael Plöd

Other Decks in Programming

Transcript

  1. Getting a better
    software architecture
    documentation with
    Domain-driven Design


    Michael Plöd

    Fellow at INNOQ

    @bitboss

    View full-size slide

  2. 2
    Speaker
    Michael Plöd


    Fellow at INNOQ


    Twitter: @bitboss

    View full-size slide

  3. Get my DDD book


    cheaper
    Book Voucher: 7.99 instead of (min) 9.99


    http://leanpub.com/ddd-by-example/c/speakerdeck

    View full-size slide

  4. 4
    I need to send a bunch of huge
    props to those folks who heavily
    inspired a lot of content in this talk
    Simon Brown
    Alberto Brandolini
    Nick Tune
    Kacper Gunia
    Gernot Starke
    Indu Alagarsamy
    …. and of course Eric Evans ….
    Many INNOQ folks (of course ;-) )
    Krisztina Hirth
    Peter Hruschka

    View full-size slide

  5. https://github.com/ddd-crew

    View full-size slide

  6. 6
    Let’s talk about documentation
    of software architecture
    f
    irst


    View full-size slide

  7. 7
    There are many great ideas already
    out there. Don’t reinvent the wheel!
    4+1 Model by Kruchten

    View full-size slide

  8. 8
    I will mainly focus on arc42 but I’ll also
    draw some parallels to the C4 diagrams
    4+1 Model by Kruchten

    View full-size slide

  9. 9
    However, we have an issue:


    Most documentation is done by software
    architects „alone in their chambers“

    View full-size slide

  10. 10
    Often this kind of documentation is
    hard to grasp for other stakeholders

    Architect Documentation

    Other stakeholders

    View full-size slide

  11. There is help


    •DDD is all about collaboration
    between domain experts and
    software engineering teams


    •DDD has concepts like the
    Bounded Context that may come
    in handy


    •With the help of some ideas of
    Domain-driven Design we will be
    able to create better
    documentation for our software
    architectures
    Domain


    Driven


    Design
    11

    View full-size slide

  12. „It is not the domain
    experts knowledge that
    goes into production, it is
    the assumption of the
    developers that goes into
    production”
    12
    Alberto Brandolini


    Inventor of EventStorming

    View full-size slide

  13. 13
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  14. 14
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  15. Ideas from the Business
    Model Canvas are a great
    input into the
    f
    irst chapter
    of the ARC42 template

    View full-size slide

  16. 17
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  17. <

    Design community>>


    Event Storming
    <

    Design community>>


    Domain Storytelling
    18
    Popular Collaborative Modelling Techniques
    <Development community>>


    Example Mapping
    <community>>


    User Story Mapping

    View full-size slide

  18. 19
    Event Storming


    Event Storming is based events which happen in a problem domain and which are
    interesting for domain experts. They are written in past tense on orange sticky notes

    View full-size slide

  19. Chaotic Exploration

    View full-size slide

  20. Enforcing the timeline

    View full-size slide

  21. Pivotal Events & Swimlanes

    View full-size slide

  22. External Systems

    View full-size slide

  23. Actors & Commands

    View full-size slide

  24. This state of an EventStorming can directly
    be merged to your documentation

    View full-size slide

  25. Arc42


    Business Scope & Context
    C4 Model


    Level 1: System Context Diagram
    Source: https://c4model.com/
    Source: https://arc42.org/overview

    View full-size slide

  26. From EventStorming


    • External Systems (pink stickies): candidates for
    software systems to integrate with


    • Actors (yellow stickies): People, user roles


    • Commands (blue stickies) or Events (orange
    stickies): actions by actors or integration towards
    software systems

    View full-size slide

  27. 28
    The context views in many software
    architecture documentation templates
    is often underestimated but it contains a
    lot of politics sometimes. It helps a lot to
    create an early and shared
    understanding.


    EventStorming helps!

    View full-size slide

  28. 29
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  29. 30
    A Bounded Context is…


    • A boundary for a model expressed in a consistent ubiquitous language tailored around
    a speci
    f
    ic purpose


    • A unit of:


    • Autonomy


    • Mastery


    • Purpose


    • A safe space for:


    • Learning domain complexity


    • Experimenting


    • Delivering high value software


    • A team
    f
    irst boundary
    This slide contains ideas from the DDD book by Eric Evans, from Alberto Brandolini and from the Team Topologies book by Mathew Skelton and Manuel Pais

    View full-size slide

  30. 31
    There are many modeling choices to
    group domain concepts

    View full-size slide

  31. 32
    „All models are wrong, but some are useful“


    Quote by George E. P. Box
    Thing Color Process

    View full-size slide

  32. Boundaries between Pivotal Events

    View full-size slide

  33. Mind the swimlanes

    View full-size slide

  34. Look for terminology

    View full-size slide

  35. Arc42


    Building Block View
    C4 Model


    Level 2: Container Diagram


    (in parts)
    Source: https://c4model.com/
    Source: https://arc42.org/overview

    View full-size slide

  36. 38
    Bounded Contexts are great candidates for
    the 1st level of the building block view in
    arc42. If you go for self-contained systems,
    they can also be good candidates for the
    container diagram in the C4 Model


    EventStorming helps in discussing „domain-
    driven software modules“ with the business
    in a collaborative way

    View full-size slide

  37. 39
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  38. 40
    Bounded Context Design Canvas


    The canvas guides you through the process of designing a bounded context by requiring you to
    consider and make choices about the key elements of its design, from naming to responsibilities, to
    its public interface and dependencies.
    Source: https://github.com/ddd-crew/bounded-context-canvas

    View full-size slide

  39. 42
    The Bounded Context Canvas, which was
    invented by NICK TUNE (great guy btw!) is not
    only a good helper in asking questions during the
    design phase it can also be your
    f
    irst bit of
    documentation for your building blocks.


    It is also a good summary for folks who are
    interested in getting an overview of your building
    blocks

    View full-size slide

  40. The Ubiquitous Languge and parts of the Business
    Decisions should be a key element of the glossary

    View full-size slide

  41. How do we get the In- and Outbound Communication?

    View full-size slide

  42. 46
    https://github.com/ddd-crew/ddd-starter-modelling-process

    View full-size slide

  43. 47
    Domain Message Flow Modelling


    A Domain Message Flow Diagram is a simple visualisation showing the
    f
    low of messages
    (commands, events, queries) between actors, bounded contexts, and systems, for a single scenario.
    Source: https://github.com/ddd-crew/domain-message-
    f
    low-modelling

    View full-size slide

  44. Domain Message
    f
    lows are


    a good 1st
    f
    it for the arc42


    runtime view


    View full-size slide

  45. They can
    also be easily
    transformed
    towards the
    dynamic
    diagram of
    the C4 Model


    Image Source: https://c4model.com/

    View full-size slide

  46. 51
    One more thing….


    Think about chapter 10 of the arc42
    template: quality requirements


    Aren’t they hard to obtain from your
    stakeholders?

    View full-size slide

  47. prioritization
    consolidation
    broad collection
    preparation
    Quality Storming

    View full-size slide

  48. The end result of a

    Quality Storming Workshop:


    A set of prioritized quality requirements

    View full-size slide

  49. Read the full


    description on


    innoq.com


    (in English and German)
    https://www.innoq.com/en/articles/2020/02/quality-storming-workshop/

    View full-size slide

  50. Summary:


    Ideas and concepts behind DDD are a good
    f
    it for getting a
    better documentation and design of your software
    Big Picture EventStorming
    Bounded Contexts
    Domain Message Flows
    Quality Storming
    Ubiquitous Language

    View full-size slide

  51. Get my DDD book


    cheaper
    Book Voucher: 7.99 instead of (min) 9.99


    http://leanpub.com/ddd-by-example/c/speakerdeck

    View full-size slide

  52. Krischerstr. 100


    40789 Monheim am Rhein


    Germany


    +49 2173 3366-0
    Ohlauer Str. 43


    10999 Berlin


    Germany


    +49 2173 3366-0
    Ludwigstr. 180E


    63067 Offenbach


    Germany


    +49 2173 3366-0
    Kreuzstr. 16


    80331 München


    Germany


    +49 2173 3366-0
    Hermannstrasse 13


    20095 Hamburg


    Germany


    +49 2173 3366-0
    Gewerbestr. 11


    CH-6330 Cham


    Switzerland


    +41 41 743 0116
    innoQ Deutschland GmbH innoQ Schweiz GmbH
    www.innoq.com
    57
    Thank you!


    Michael Plöd


    Follow me on Twitter: @bitboss

    View full-size slide