Architecture Decision Record

Active theme: Light

← documenten

Suggesties voor het schrijven van goede ADR's

Kenmerken van een goede ADR:

  • Onderbouwing: leg uit waarom de AD wordt uitgevoerd. Dit kan context omvatten (zie hieronder), voor- en nadelen van verschillende mogelijke opties, functievergelijkingen, kosten-batenanalyses enzovoort.

  • Specifiek: elke ADR moet over één AD gaan, niet over meerdere AD's.

  • Tijdgestempeld: geef aan wanneer elk item in de ADR is geschreven. Dit is vooral belangrijk voor aspecten die in de loop van de tijd kunnen veranderen, zoals kosten, planning, uitbreiding enzovoort.

  • Onveranderlijk: wijzig bestaande informatie in een ADR niet. Wijzig de ADR in plaats daarvan door nieuwe informatie toe te voegen, of vervang de ADR door een nieuwe ADR te maken.

Kenmerken van een goede sectie "Context" in een ADR:

  • Beschrijft de situatie van de organisatie en de zakelijke prioriteiten.

  • Bevat de onderbouwing en overwegingen op basis van de sociale en technische samenstelling van het team.

  • Bevat relevante afwegingen, uitgedrukt in termen die passen bij de behoeften en doelen.

Kenmerken van een goede sectie "Gevolgen" in een ADR:

  • Beschrijft wat er volgt uit het nemen van de beslissing. Dit kunnen effecten, resultaten, opleverbare producten, vervolgacties enzovoort zijn.

  • Bevat informatie over vervolg-ADR's. Het komt relatief vaak voor dat één ADR de behoefte aan meer ADR's oproept. Als een ADR bijvoorbeeld een grote, overkoepelende keuze maakt, kan dat de behoefte aan kleinere beslissingen oproepen.

  • Bevat een nabeschouwingsproces. Het is gebruikelijk dat teams elke ADR na een maand bekijken, de ADR-informatie vergelijken met wat er daadwerkelijk is gebeurd en daarvan leren en groeien.

Een nieuwe ADR kan een eerdere ADR vervangen:

  • Wanneer een AD wordt genomen die een eerdere ADR vervangt of ongeldig maakt, moet een nieuwe ADR worden geschreven