Notat om arkitekturvalg

Hvad det er

Et notat om arkitekturvalg, ofte kaldet et ADR efter den engelske
betegnelse, fastholder et teknisk valg, der får væsentlige følger.
Det beskriver, hvad holdet valgte, hvilke forhold der prægede
valget, hvilke muligheder der blev overvejet, og hvilke konsekvenser
der fulgte med. Emnet kan være, hvor data ejes, hvordan to tjenester
forbindes, eller hvordan systemet skal opføre sig ved en fejl. En
kollega, der kommer til senere, kan se, hvorfor løsningen fik sin
form, og hvilke antagelser der stadig holder.

Et kort notat kan nøjes med få felter. Nummer og dato gør det muligt
at henvise til valget. Status angiver, om det er foreslået, vedtaget
eller afløst. Baggrunden beskriver problemet og de konkrete vilkår.
Beslutningen siger, hvad holdet vil gøre. Konsekvenserne omfatter
både gevinster og forpligtelser. En ny tjeneste skal måske passes,
en omstilling tager længere tid, eller en migrering skal øves.
Alternativerne skal være godt nok beskrevet til, at læseren kan
vurdere, hvorfor de var på tale.

Vælg et sted, der passer til arbejdet. Nogle hold lægger
Markdown-filer ved siden af koden og linker til dem fra den ændring,
der gennemfører valget. Andre har flere depoter og holder et fælles
indeks. En kort oversigt med status gør det let at finde den
gældende beslutning. Et brugbart notat har en stabil adresse og en
begrundelse, der kan læses uden bevismaterialet foran sig. Detaljer
kan ligge i en undersøgelse, en rapport eller et testresultat, som
notatet henviser til.

Hvorfor det betyder noget

Kode viser meget om systemet nu. Den kan også afsløre dele af
historien, men sjældent alle grunde til et valg. En læser kan for
eksempel se to databaser og foreslå at samle dem. Opdelingen kan
have været en midlertidig måde at isolere risiko på, mens en
leverandør skiftede eksportformat. Notatet kan forklare, hvad man
beskyttede, hvorfor løsningen gav mening på det tidspunkt, og hvad
der skal ske, før den tages op igen.

Notatet gør det lettere at være konkret uenig. En foreslået
afhængighed kan fjerne behovet for selv at programmere en planlægger
for tilbagevendende job. Den kan samtidig kræve en vagt, der ved,
hvordan jobtilstanden genoprettes. En reviewer kan undersøge, om den
vagt findes, og om den nye udgift passer til besparelsen. Driftsfolk
og andre læsere kan se afvejningen, mens den stadig kan ændres.
Efter vedtagelsen står samme forklaring til rådighed ved
overdragelse og senere fejlretning.

Det giver især mening at skrive notatet, når det er krævende at gøre
valget om. En ændring af et feltmærkat hører oftest hjemme i
ændringshistorikken. Valget af, hvilken tjeneste der ejer ordrer,
eller hvordan dobbelte betalinger håndteres, påvirker flere hold og
er dyrere at revidere. Beskriv det vigtige valg, mens mulighederne
stadig er friske. Gem den viden, der faktisk var til rådighed,
sammen med datoen og årsagen.

Sådan ser det ud i praksis

I porteføljens beskrivelse af en platforms grundlæggende tekniske
valg blev centrale teknologier valgt sammen med retningen for
produktet. Den slags beslutning er værd at kunne forklare
efterfølgende. Her er et fiktivt eksempel på at skrive et lignende
valg om dataejerskab ned.

En forsendelsestjeneste har en database med ordrer og en offentlig
side, hvor kunden kan se sin egen ordres status.
Forsendelseshændelser kommer af og til for sent, og en visning må
aldrig afsløre en anden kundes ordre. Holdet vælger at vise status
fra en særskilt læsemodel, som kun får godkendte felter. En direkte
læsning ville kræve færre komponenter og normalt give friskere data.
Til gengæld ville den føre offentlig trafik og en ny adgangsgrænse
tæt på det autoritative register. Et genbrug af den natlige eksport
ville være nemmere at indføre, men ændringer samme dag ville mangle.

Følgerne giver konkrete opgaver. Support skal kunne se, om visningen
er forsinket, så de ved, hvornår de skal bruge deres interne
procedure. Et tjek af kontrakten kan opdage et nyt felt, før det
kommer med i visningen. Nogen får ansvar for jobbet og dets alarm.
Aftalen er at tage valget op igen, hvis forsinkelsen overskrider
grænsen i to travle uger, eller hvis adskillelsen ikke længere er
nødvendig. Link beslutningen til undersøgelsen og det relevante
tjek, så næste læser kan følge ræsonnementet.

Når et nyt valg erstatter det hidtidige, så giv det sin egen post og
link mellem de to. Den gamle forklaring gælder stadig for en ældre
version. Med status og dato i listen kan en kollega finde den
aktuelle beslutning uden at læse samtlige anmeldelser af ændringen.

Før den offentlige tjeneste svarer, kontrollerer den, at læseren har
adgang til netop den ordre. Afprøv både afvisning ved opslag på en
anden kundes ordre og præcis hvilke felter den tilladte visning
leverer.

Hvor det går galt

Et svagt notat gør kun det foretrukne alternativ attraktivt. Giv
hver mulighed den stærkeste begrundelse, den faktisk havde. Læseren
kan så se, hvorfor en anden valgmulighed kunne passe under andre
vilkår. Knyt relevante krav til den aftale, måling eller forskrift,
der lå bag. En standardskabelon skal give plads til de særlige
forhold, der afgjorde sagen.

En anden fejl er at nævne gevinsterne uden at give nogen ansvaret
for omkostningerne. En ny database eller fælles kø ændrer andre
menneskers arbejde. Gør det klart, hvem der overtager drift og
vedligehold, og hvordan en adgangsgrænse holdes. Hvis en følge endnu
ikke kan afprøves, så angiv, hvilken observation der bliver
relevant, og hvornår man har mulighed for at se den.

Hold endelig notatet kort nok til at blive skrevet, før beslutningen
er glemt. Læg vejledning og driftsprocedure det sted, hvor de kan
ændres uafhængigt. Når forholdene udløser et nyt valg, så bevar den
gamle forklaring og vis, hvilken beslutning der nu gælder. En læser
skal kunne bruge den korte historik til at afklare et konkret
spørgsmål.

Læs mere

  * AWS om processen for at dokumentere arkitekturvalg

  * Microsoft Azure Well-Architected om beslutningsnotater

  * Den britiske regerings ramme for arkitekturbeslutninger

hDenne side på nettet	URL:https://engineer.company/da/glossary/architecture-decision-record/	engineer.company	70
