TranskribatorTranskribator
Een architectuurbesluit vastleggen met een opname van het overleg
Bewaar de reden voor de keuze

Een architectuurbesluit vastleggen met een opname van het overleg

Een ADR documenteert één belangrijk architectuurbesluit: de context, alternatieven, keuze, gevolgen en status. Een transcript helpt argumenten terug te vinden. De deelnemers controleren de technische juistheid.

Het Transkribator-team5 min leestijd
BRONADRContext en beslisfactorenOverwogen optiesKeuze en redenGevolgen en herzieningVAN WOORDEN NAAR RESULTATEN
Werken met een echte opnameIllustratief oefenvoorbeeldSjabloon om te kopiëren
Bewaar de reden voor de keuze

Zo schrijf je een Architecture Decision Record op basis van een opname

Een ADR documenteert één belangrijk architectuurbesluit: de context, alternatieven, keuze, gevolgen en status. Een transcript helpt argumenten terug te vinden. De deelnemers controleren de technische juistheid.

Een transcript maakt het mogelijk om formuleringen te controleren. Het bewaart context, voorbehouden en de volgorde van de argumenten. De schrijver bepaalt de definitieve tekst en laat die door de deelnemers controleren.

Werkwijze

Schrijf het ADR stap voor stap

  1. Kies één besluit

    Leg elk zelfstandig architectuurbesluit apart vast.

  2. Beschrijf de context

    Noteer de factoren en beperkingen die het besluit nodig maakten.

  3. Vergelijk de opties

    Bewaar de belangrijkste voor- en nadelen en redenen om elke optie af te wijzen.

  4. Benoem de gevolgen

    Noteer voordelen, kosten, nieuwe beperkingen, risico’s en wanneer een herziening nodig is.

Uitgewerkt voorbeeld

Voorbeeld: opslag voor audiobestanden kiezen

Dit is een fictief oefenvoorbeeld. Namen, omstandigheden en resultaten dienen alleen om de werkwijze uit te leggen.

Fragment uit een oefenopname · 12:40
‘Objectopslag is goedkoper voor het archief, maar we hebben een aparte manier nodig om tijdelijke links te maken.’

Context: de opnamen zijn groot, toegang moet verlopen en het uitgeven van links vraagt om controle. De keuze valt op objectopslag. Naast kosten tellen schaalbaarheid en het toegangsmodel mee.

Noem de werkzaamheden en risico’s: tijdelijke links, geldigheidscontrole, logging en tests bij storingen. Verandert de aanname over de kosten, vervang het ADR dan door een nieuw exemplaar met behoud van de geschiedenis.

Context en beslisfactorenOverwogen optiesKeuze en redenGevolgen en herziening
Een ADR legt de keuze en de afweging vast
OnderdeelBruikbare tekstTe vermijden voorbeeld
ContextGrote bestanden en beperkte toegangWe hebben nieuwe opslag nodig
OptiesObjectopslag / bestandsopslagWe kozen het beste
BesluitObjectopslag om redenen A en BDe architect heeft beslist
GevolgenTijdelijke links en monitoringGeen nadelen
Kant-en-klaar sjabloon

ADR-sjabloon

Kopieer het sjabloon en vul het in aan de hand van een specifieke opname. Geef aannames als hypotheses weer.

WerksjabloonSelecteer en kopieer
Titel en status:
Datum en deelnemers:
Context en beperkingen:
Overwogen opties:
Besluit en redenen:
Gevolgen, risico’s en reden voor herziening:
Het resultaat controleren

Vier controles vóór het versturen

  • Het document beschrijft één besluit.
  • De context vermeldt werkelijke beperkingen.
  • Alternatieven en redenen om ze af te wijzen zijn vastgelegd.
  • Nadelen en een aanleiding voor herziening zijn opgenomen.
OverlegLeg alle argumenten vastContextVerzamel factoren en optiesBesluitNoteer keuze en statusGeschiedenisVervang het oude ADR door een gekoppeld document
Van opname naar een controleerbaar en bruikbaar document
Veelgestelde vragen

Een nadere blik

Mag je een geaccepteerd ADR aanpassen?

Je kunt typefouten herstellen. Leg een gewijzigd besluit vast in een nieuw ADR dat verwijst naar het vorige.

Moet je het transcript naast het ADR bewaren?

Een link naar de interne bron en een tijdcode zijn doorgaans genoeg om een betwiste formulering te controleren.

Verder werken met de opname