Notat om arkitekturvalg

Hva det er

Et notat om arkitekturvalg, ofte kalt ADR, er en kort beskrivelse av
et teknisk valg som får betydning for systemet videre. Det forteller
hva teamet valgte, hvilke forhold som gjorde et valg nødvendig,
hvilke alternativer som var aktuelle, og hvilke følger teamet
godtok. Det kan handle om eierskap til data, grensen mellom
tjenester eller hvordan systemet skal håndtere en bestemt feil. En
kollega som kommer til senere, kan finne ut hvorfor denne løsningen
finnes, og om forutsetningene fremdeles holder.

Et lite sett med felt gir en nyttig struktur. Et nummer og en dato
gjør det mulig å vise til notatet. En status sier om valget er
foreslått, vedtatt eller avløst. Bakgrunnen beskriver problemet og
vilkårene som gjaldt. Beslutningen sier hva teamet skal gjøre.
Konsekvensene beskriver både hva valget gir og hva det krever.
Eksempler er en ny tjeneste som må driftes, et nytt ansvar hos
beredskapen eller en migrering som bør øves på. Beskriv
alternativene tilstrekkelig til at leseren kan se avveiningen.

Bruk et sted folk allerede finner frem på. Et team kan lagre
notatene ved siden av koden og lenke fra endringen som gjennomfører
vedtaket. Flere team kan trenge en felles indeks dersom avgjørelsen
gjelder flere kodebaser. Det viktige er en stabil adresse og en
begrunnelse leseren kan forstå. Rapporter, målinger og tester kan
ligge andre steder og likevel være enkle å finne gjennom lenkene i
notatet.

Hvorfor det er viktig

Koden viser mye om dagens løsning, men forteller lite om mulighetene
man la bort. En ny medarbeider ser to databaser og mener de kan slås
sammen. Oppdelingen kan ha vært et midlertidig grep for å holde en
risiko avgrenset mens en leverandør skiftet eksportformat. Notatet
kan beskrive hva man beskyttet, hvorfor delingen var fornuftig den
gangen og når den bør vurderes på nytt. Da slipper neste team å
gjenta hele undersøkelsen.

Et beslutningsnotat gjør det også mulig å være konkret uenig. Et
forslag kan beskrive hvordan en ny avhengighet gjør egen kode for
planlegging overflødig. Samtidig krever den at noen kan gjenopprette
tilstanden i planleggeren etter et avbrudd. En kollega kan spørre
hvem som faktisk har vakt og om gevinsten svarer til det nye
ansvaret. Driftsfolk kan lese samme begrunnelse før valget tas.
Senere kan den som tar over, se hva som ble lovet og hvor ansvaret
ligger.

La kostnaden ved å gjøre om valget avgjøre hvor mye du skriver. Et
nytt ord i et skjema kan vanligvis forklares i endringshistorikken.
Å flytte eierskap til ordre mellom tjenester eller endre
behandlingen av doble betalinger får følger for flere team. Beskriv
det viktigste mens valgmulighetene er ferske, og ta vare på
opplysningene som faktisk lå til grunn. Da er det enklere å vurdere
et senere forslag uten å gi gårsdagens beslutning dagens kunnskap.

Slik ser det ut i praksis

Porteføljen beskriver de grunnleggende tekniske valgene for en
plattform da produktet og den tekniske retningen tok form. Slikt
arbeid gir beslutninger det er nyttig å kunne forklare senere.
Eksemplet nedenfor er konstruert for å vise hvordan et notat kan
dokumentere eierskap til data.

En frakttjeneste har en ordredatabase og en offentlig side der
kunden ser sin egen forsendelse. Utsendingshendelser kommer av og
til sent, og visningen må aldri avsløre en annen kundes bestilling.
Teamet vedtar å hente status fra en separat lesemodell med bare
godkjente felt. Et direkte oppslag ville krevd færre deler og
vanligvis gitt ferskere opplysninger, men ville ført offentlig
trafikk og et nytt tilgangsskille helt inn til hovedregisteret. En
nattlig eksport hadde vært rask å gjenbruke, men ville skjult
endringer i løpet av dagen.

Konsekvensene gir oppgaver. Brukerstøtten må kunne se forsinkelsen
og vite når en intern rutine bør brukes. En kontrakttest kan oppdage
felt som ikke er godkjent for visningen. Noen må ha ansvar for
oppdateringen og varselet. Teamet avtaler å vurdere valget på nytt
hvis forsinkelsen overstiger grensen i to travle uker, eller hvis
kravet om adskillelse endres. Notatet lenker gjennomgangen og
testen. Neste person kan finne grunnen til den ekstra delen og det
som må sjekkes før den kan erstattes.

Når et annet valg blir vedtatt, opprett et nytt notat og lenk i
begge retninger. Status og dato viser hvilket valg som gjelder nå.
Den tidligere forklaringen kan fortsatt være nødvendig når en feil
undersøkes i en eldre versjon.

Den offentlige løsningen kontrollerer at brukeren har tilgang til
akkurat den ordren før den viser status. Test avslag ved oppslag på
en annen kundes ordre og det nøyaktige feltsettet i et tillatt svar.

Hvor det går galt

Et notat kan bli en pyntet begrunnelse hvis bare den valgte
løsningen får en rettferdig beskrivelse. Gi hvert reelt alternativ
de beste argumentene som talte for det. Knyt viktige påstander til
målingen, standarden eller begrensningen som lå til grunn. Da kan en
leser se hvorfor det samme alternativet kan passe i en annen
situasjon.

En annen feil er å utelate hvem som skal bære kostnaden. En ny
database eller en delt kø endrer en annens arbeidsdag. Beskriv hvem
som følger opp drift, sikkerhetsgrenser og vedlikehold. Dersom en
viktig konsekvens foreløpig ikke kan prøves, avtal hva som skal
observeres og når teamet kan lære om den. Behold nok sammenheng til
at neste person kan kjenne igjen den opprinnelige situasjonen.

Skriv kort nok til at notatet blir ferdig mens avgjørelsen tas.
Driftsprosedyrer kan forandres ofte og passer som egne dokumenter.
Når et valg faktisk endres, før den nye avgjørelsen ved siden av det
gamle resonnementet og pek leseren mot det som gjelder.

Les mer

  * AWS om prosessen for å dokumentere arkitekturvalg

  * Microsoft Azure Well-Architected om beslutningsnotater

  * Den britiske regjeringens rammeverk for arkitekturbeslutninger

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