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.
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.
Schrijf het ADR stap voor stap
Kies één besluit
Leg elk zelfstandig architectuurbesluit apart vast.
Beschrijf de context
Noteer de factoren en beperkingen die het besluit nodig maakten.
Vergelijk de opties
Bewaar de belangrijkste voor- en nadelen en redenen om elke optie af te wijzen.
Benoem de gevolgen
Noteer voordelen, kosten, nieuwe beperkingen, risico’s en wanneer een herziening nodig is.
Voorbeeld: opslag voor audiobestanden kiezen
Dit is een fictief oefenvoorbeeld. Namen, omstandigheden en resultaten dienen alleen om de werkwijze uit te leggen.
‘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.
| Onderdeel | Bruikbare tekst | Te vermijden voorbeeld |
|---|---|---|
| Context | Grote bestanden en beperkte toegang | We hebben nieuwe opslag nodig |
| Opties | Objectopslag / bestandsopslag | We kozen het beste |
| Besluit | Objectopslag om redenen A en B | De architect heeft beslist |
| Gevolgen | Tijdelijke links en monitoring | Geen nadelen |
ADR-sjabloon
Kopieer het sjabloon en vul het in aan de hand van een specifieke opname. Geef aannames als hypotheses weer.
Titel en status: Datum en deelnemers: Context en beperkingen: Overwogen opties: Besluit en redenen: Gevolgen, risico’s en reden voor herziening:
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.
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.