Notat om arkitekturvalg
et kort notat om designvalget og dets begrundelse
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.

Foto: Engin_Akyurt / Pixabay 
Foto: BRRT / Pixabay
Brug begrebet i en beslutning
Brug »Hvad er et notat om arkitekturvalg?« i en konkret beslutning. Vi kan knytte begrebet til det system, I bygger eller køber. Systemets form lagt fast på papir først, så delene passer sammen, og prisen er kendt, før nogen skriver kode.
Undersøg antagelserne bag ordet
Brug forklaringen og det tilknyttede arbejde til at formulere spørgsmål til jeres projekt. Vi kan undersøge antagelserne sammen, før et værktøj vælges. Én infrastrukturplan til 14 afdelinger — 14 forskningsafdelinger på én infrastrukturplan
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.

