C4 & Continuous Documentation

Deze les gaat over een van de 'Continuous Everything' zaken, namelijk Continuous Documentation. We kijken naar het C4 model van Simon Brown: Documentation for developers by developers! Daarna wat highlights van werk van HAN docent-onderzoeker Theo Theunissen rondom documentation in Continuous Software Development. Daarna naar Architecture Decision Records.

Maar eerst doen we een korte recap en aanvulling op InfoSupport's workshop over Domain Driven Design.

1. DDD + Microservices recap

Korte terugblik workshops over DDD respectievelijk microservices.

Samen bespreken DDD's strategic vs. tactical patterns, en korte recap van de 3 hoofd strategic patterns:. Na de bespreking snap je deze termen hopelijk en kun je dit uitleggen. Anders geeft de website infiniot deze korte definitie, en moet je een bron vinden die het uitgebreider uitleggen:

  • *Ubiquitous Language – Een taal gestructureerd rond het domeinmodel en gebruikt door alle teamleden om alle activiteiten van het team met de software te verbinden.
  • Bounded Context – Een beschrijving van de grens waarbinnen een bepaald model wordt gedefinieerd.
  • Context mapping - Hoef je in deze cursus hoef je deze niet te kennen.

Deze laatste hangt wel vrij direct samenahngt met de andere twee, zoals een student al aangaf. En in de PitStop casus uit eindopdracht course fase zit een mooi voorbeeld van een Context Map waar je mee te maken krijgt.

Ubiquitous language betekenis via Google Translate

Figuur 1: Ubiquitous betekenis (bron: Google translate)

Wellicht ken je al 'onion' of 'Ports and Adapters' architectuur. Hierbinnen zitten ook DDD tactical patterns als 'Repository' en 'Services' (met onderscheid tussen Application Services (technische glue) en Domain Services (business logica).

Onion architecture with 'lower level' DDD patterns

Figuur 2: DDD Tactical patterns: Onion architecture with 'lower level' DDD pattern (bron: Jordan Jordanov, J., Petrov P, 2023)

We zoomen in op de andere DDD tactical patterns:

DDD Tactical patterns: Aggregate met Aggregate root en Entity vs Value object

Figuur 3: DDD Tactical patterns: Aggregate met Aggregate root en Entity vs Value object (bron: .NET Microservices Architecture for Containerized .NET Applications Figure 7-9. p. 203

Dit zijn meer 'implementatie in OO' gerichte patterns: Entity, Value Object en Aggregate. Een Aggregate geeft een idee van de minimale 'grootte' van een microservices definieren/beschrijven, Zoals je bv. leest in een online artikel van Microsoft Learn of Dave Taubler op Medium (edit 2024: helaas inmiddels achter paywal/abonnement):

"As a general principle, a microservice should be no smaller than an aggregate, and no larger than a bounded context. First, we’ll review the tactical patterns.” - Microsoft Learn (z.d.)

"... we [..] designed our microservices around Aggregates" - Dave Taubler (2020)

2. Continuous Documentation

Relevante vragen:

  • Wat houdt 'Continuous Documentation' in?
  • Wat is de relatie met 'Continuous Delivery' (en andere uit 'Continuous Everything'?)
  • Kun je een praktijk voorbeeld van Continuous Documentation geven?
  • Welke manieren van documenteren van Software ken je? (deliverables, methodes)
  • Open vraag: Welke documentatie gebruik je binnen 'Ops werk'?
C4 model overzicht

De 3 fasen van software documentatie volgens Theunissen (2021) (klik via 'Publicaties' onder https://theotheunissen.nl.

Lesopdracht: Maak een opsomming van veel vormen van documentatie die je als ICT'er in je opleiding/werkervaring bent tegengekomen. Verdeel deze daarna onder over de 3 fases;

  1. Upfront: Acquiring knowledge
  2. Development: Building knowledge
  3. Delivery: Transferring knowledge

Zijn er ook types die in meerdere fases horen?

3. Het C4 model

De sheets van deze workshop.

C4 model overzicht

Figuur 1: © Simon Brown, c4model.com

All parts, no use All parts, no use We need overview

4. ADR's

Software Architectuur is het deel van de (software) design dat moeilijk te veranderen is. Je ontwerp leg je op verschillende niveaus vast met C4 en UML diagrammen en goede toelichtingen hierbij. Om verdere 'onderweg gemaakte' keuzes vast te leggen gebruiken we in deze minor Architecture Decision Records (ADR). ADR's zijn een heel belangrijk iets voor Software Architecten, maar ook Software Developers zoals beargumenteert in dit IEEE explore blog (2022)):

"ADRs’ greatest strength is their low barrier to entry. Since anyone on the team can write an ADR, everyone who wants can fill the role of software architect." - Michael Keeling (2022)

Hoe je deze keuzes vastlegt (documenteert) is weer een keuze op zich. Maar sowieso is het idee 'lichtgewicht' en direct bij de code in een tekst format, typisch markdown. Want de doelgroep is toch: mede developers/architects, kortom ICT'ers (en niet domein/business stakeholders, daar zijn andere docmenten voor). Hierbij is het handig een template te gebruiken. Om de keuze stress op dit niveau wat te beperken, en zo te kunnen focussen op concretere en relevantere keuzes in techniek en domein modelleren beperken we in deze minor de opties hiervoor tot twee:

  1. Wellicht wel de best optie is een heel korte en krachtige variant van ADR's genaamd y-statements (DocSoc, 2020). Dit is feitelijk een enkele zin, maar hierin zit ook al een stuk 'alternatives':

  2. Of je gebruikt het template van Nygard, één van de grondleggers, volgens een artikel van Michael Keeling (2022). Omdat een ‘decision’ (=beslissing) ook opties impliceert (anders kies je nergens tussen) nemen we hierin ook alternatieven op. In het template van Nygard zit geen apart kopje, maar zouden alternatieven dan onder kopje 'Decisions' moeten. Of je plaatst ze al direct in de Context' (zoals Nygard zelf deed in het artikel waarin hij ADR's introduceerde (Nygard, 2011). Maar in het kader van het 'single responsibility' principe voeg je ten opzichte van Nygard's template een extra kopje toe: `Alternatieven'. IN het kader van ['The pyramid principle'] (Minto, 2002) plaats je deze sectie ACHTER de 'Decision'

Binnen DevOps mag je echter afwijken van rigide standaarden, als er een goede reden is, het gaat immers om "Individuals and interactions over processes and tools" (Agile Manifesto, Fowler et al., 2001). DevOps over ligt immers in het verlengde van Agile (embrace change).

Dit is een heel stuk korter dan de volledige ADR in Nygard (Henderson, 2023) met kopjes:

  • Status: What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
  • Context: What is the issue that we're seeing that is motivating this decision or change?
  • Decision: What is the change that we're proposing and/or doing?
  • Consequences: What becomes easier or more difficult to do because of this change?

Zie voor een voorbeeld voor de PriemChecker casus de docs/ADR folder in de (PriemChecker repo) voorbeeld van standaard straks in het project.

"In the context of storing large prime candidates in our SQL database using Entity Framework Core, facing the need to accurately store numbers larger than the built-in SQL data types can handle, we decided for using a Value Converter to convert BigInteger to a string format for storage, and against using decimal or bigint storage formats, to achieve compatibility with extremely large numbers while maintaining database flexibility, accepting that this introduces performance overhead from conversion and adds complexity in the application logic."

Hieronder nog iets over de folderstructuur in dit project.

Folder structuur en toepassen Pyramid principle in documentatie

Qua folder structuur zet je de ADR's in folder /docs/adr en zet in zowel docs/ als docs/adr ook een README.md als 'landingspagina. De README.md onder adr geeft deze inleiding/leeswijzer en linkt naar alle ADR’s. Dit is ook de DoD (Definition of Done) voor ADR’s, namelijk het Nygard template format dat jullie hanteren (Henderson, z.d.) of Y-statements (Olzzio, 2023)

Ook kun je verbanden leggen tussen verschillende ADR's. Als je bv. in het begin van je project kiest voor dataopslag met SQL Server, en dit vastlegt in een ADR, en gaande het project, bv. vanwege geheugengebruik issues van SQL switcht naar meer light weight database als PostgreSQL kun je deze aan elkaar koppelen. Of juist naar MongoDB vanwege partitioning eisen, of wat dan ook. Ook heb je keuze om hierbij twee technologie specifieke ADR's te maken (e.g. ADR-SqlServer.md en ADR-PostgreSQL.md) of een enkele ADR, met een meer functionele/semantische naam Data-Persistence.md die je aanpast. In de paragraaf hieronder een voorbeeld van een te gebruiken tekst. Zoals hier aangeven gebruik het 'standaard format van Nygard, maar vul deze aan met 'Alternatives'. Of - als je het graag zo kort mogelijk houdt - kijk eens naar 'y-statements' van Olzzio (2023).

Quiz

Test je kennis over continuous documentation en C4 met deze korte multiple choice quiz.

Leerdoelen

Check met onderstaande leerdoelen of je de behandelde stof begrepen hebt en toetsvragen kunt beantwoorden.

  • Je kunt uitleggen wat Continuous Documentation is en hoe het zich verhoudt tot Continuous Delivery.
  • Je kent praktijkvoorbeelden van Continuous Documentation en kunt verschillende manieren van documenteren van software beschrijven.
  • Je kunt het C4 model uitleggen en beschrijven hoe het helpt bij het documenteren van softwarearchitectuur binnen DevOps teams.
  • Je kent twee manieren van architectuur beslissingen vastleggen met ADR's die je in het DevOps project gaat gebruiken
  • Je kent de belangrijkste strategic DDD patterns zoals Ubiquitous Language, Bounded Context, en Context Mapping, en kunt het onderscheid uitleggen tussen strategic en tactical patterns.
  • Je kunt voorbeelden geven van tactical DDD patterns zoals Entity, Value Object, en Aggregate, en weet dat aggregates een indicatie geven van minimale grootte van microservices.

Bronnen

Hier (nogmaals) de bronnen gebruikt op deze pagina in APA format.

Last change: 2025-01-13