Architectural Decision Record

Tags: , , Published On: augustus 2, 2022

Ik ben ervan overtuigd dat er niet zoiets bestaat als “slechte” of “goede” architectuur. Ofwel past het bij de technische behoeften van een bedrijf, ofwel niet. Een technisch design is altijd het resultaat van een reeks “keuzes” en “beslissingen” doorheen het ontwerpproces. Maar het is nooit goed of slecht, het gaat erom hoe geschikt het technisch design is, rekening houdend met de huidige en voorbije beperkingen en eisen.

Het is van cruciaal belang dat je een “verslag” of “logboek” bijhoudt van de beslissingen die je maakt tijdens het ontwerpproces. Zo stel je de reden vast waarom het design zich op een gegeven moment in een bepaalde toestand bevindt. Dit artikel heeft als doel developers en architecten te helpen met het creëren van zo’n “logboek met besluitvormingsprocessen”. Daarbij zullen we gebruik maken van Architectural Decision Records (ADR’s), zoals dat heet.

De kunst van beslissingen nemen

Op regelmatige basis beslissingen nemen, brengt bij bepaalde personen onzekerheid en angst met zich mee. Vooral als die beslissing een grote invloed op je design heeft. Heb ik hier wel lang genoeg over nagedacht? Heb ik voldoende data overwogen? Uiteindelijk ontdek je dat je nooit voldoende data kan onderzoeken. De hoeveelheid data voor een bepaalde kwestie is oneindig

Zo zijn piekeraars personen die denken aan zaken die buiten hun controle liggen. Ze denken aan wat zou kunnen gebeuren. Als gevolg daarvan maken ze zich zorgen om de verkeerde beslissing te nemen.

Ter verduidelijking: ik probeer hier niet te vertellen dat je niet over je beslissingen mag nadenken. Maar je zou nooit bang mogen zijn om er één te nemen. Zelfs al is iedere beslissing die je neemt tijdens het ontwerpen verkeerd, zolang je design evolueert, ben je op de goede weg. En zolang je een logboek bijhoudt van je besluitvormingsproces, open je deuren naar een nieuwe weg waarin je fouten kan rechtzetten.

ADR’s

Je technische documentatie zou uit verschillende “types” moeten bestaan. Denk maar aan een high level (systeem)design, een applicatieontwerp, infrastructuur details, enz.
Hoewel ADR’s eerder atypisch zijn, zouden ze niet (!) gezien mogen worden als vervanging van andere soorten technische documentatie!

De naam zegt het zelf: een Architectural Decision Record is een logboek van beslissingen die een team neemt tijdens de ontwikkeling van het design van hun applicatie. Dit kan op verschillende manieren gedocumenteerd worden met behulp van allerlei soorten templates. Het moet echter altijd de volgende informatie bevatten:

  • ADR Lead
    De persoon (of personen) die de leiding heeft (hebben) over de ADR.
  • Status
    De toestand van de ADR in zijn levenscyclus. Mogelijke voorbeelden hiervan zijn “Draft”, “In Review”, “Decision Presented”, “Closed”.
  • Context
    De context van het probleem waarvoor de ADR een oplossing zal bieden. Wat probeer je te beslissen? Welk probleem probeer je op te lossen?
  • Oplossing(en)
    Zodra je het probleem hebt vastgesteld, denk je na over verschillende oplossingen. Probeer er altijd meer dan één te formuleren! Daardoor moet je out of the box denken, meerdere voor- en nadelen afwegen, implementatiekosten in overweging nemen, enz.
  • Risicoanalyse
    Een soort risicoanalyse. In welke mate brengt het probleem risico’s met zich mee? Hoe zullen de verschillende oplossingen die risico’s beperken?
  • Requirements
    Aan welke requirements moet worden voldaan? Je kan de MoSCoW methode gebruiken, of een ander systeem dat je nuttig vindt. Zorg ervoor dat je eisen kraakhelder zijn!
  • Schattingen
    Hoeveel zal iedere oplossing kosten? Dit zal je uiteindelijke beslissing beïnvloeden en is daarom een belangrijk deel van het ADR. De oplossing die het beste lijkt, zal niet altijd de juiste zijn. Het moet vooral realistisch zijn: daarvoor is een kosten baten analyse van essentieel belang.
  • De beslissing!
    Uiteindelijk zul je een beslissing moeten nemen. Die zal op zijn beurt worden voorgesteld aan het projectmanagement. Je zult in staat moeten zijn om uit te leggen wat je doet, waarom je het moet doen en hoeveel tijd je nodig hebt om het te doen.
    Let erop dat alle voorgaande stappen formaliteiten zijn die ervoor zorgen dat je het best mogelijke besluit neemt en daarbij rekening houdt met zoveel mogelijk gegevens.

Maak je gebruik van een ADR in je technische workflow, dan documenteer je weloverwogen beslissingen op een formele manier. Een design record is gecreëerd voor toekomstig gebruik. Je kan dit gebruiken om je beslissingen op een formele en overtuigende manier aan het management voor te stellen.

Een samenvatting van een oplossing zal er ongeveer uitzien zoals de onderstaande afbeelding.

Besluitvormingsproces

Zo, ik legde het wat, wie en waarom van ADR’s uit. Laat ons nu eens kijken naar de hoe. Bij het opstellen van ADR’s, houd je rekening met het volgende:

  • Het hoofddoel is het definiëren van je besluitvormingsproces.
  • Een ADR moet altijd een persoon als lead hebben die verantwoordelijk is voor het onderzoeken van het probleem. Eenaanbevolen oplossing kiezen, is de verantwoordelijkheid van het hele team. Groen licht geven voor die oplossing, is de verantwoordelijkheid van het management.
  • Het hele team moet betrokken worden bij de totstandkoming van het ADR. Iedereen moet het onderzoek begrijpen, alsook het besluitvormingsproces. De conclusie moet unaniem zijn. Een ADR is een levend document! Iedereen heeft inspraak, iedereen kan het bekijken en iedereen heeft stemrecht. Hoe meer mensen erbij betrokken zijn, hoe beter de beslissing zal zijn.
  • Laat alle leden van je team eens het voortouw nemen bij een ADR. Zo krijgt iedereen de kans om meer ervaring op te doen, out of the box te leren denken en meer vertrouwen in het besluitvormingsproces te krijgen.

Conclusie

Een Architectural Decision Record is een krachtig hulpmiddel om het besluitvormingsproces van bepaalde stappen tijdens de ontwikkeling van een design vast te leggen.
Betekent dit dat je met behulp van ADR’s automatisch alle juiste beslissingen zult nemen? Nee. Wel geeft het inzicht in waarom bepaalde keuzes zijn gemaakt. Blijkt de beslissing die je nam de verkeerde te zijn? Dan is het een meerwaarde dat je vat krijgt op het waarom. Wie nam de beslissing, beschikte hij of zij over de juiste informatie, zag iemand anders het probleem op een andere manier? Dit soort informatie is uiterst waardevol om je design te ontwikkelen op de manier die je wilt, alsook om meer ervaring op te doen op het gebied van ontwerpen.

Een dikke merci aan Karin Wauters en Marijke Walgraeve om dit blogbericht na te kijken.

Artikel geschreven door Tim Sommer

Share this blogpost