anders lisdorf bloghoved

Drømmen om letvægt - Arkitektur og dokumentation

Arkitektur og dokumentation er vigtigt, men det er klart nok ikke det som får pengene til at rulle ind i firmaet isoleret set. Det er typisk heller ikke det som får udviklerne til at juble. Arkitektur er derfor noget man lader opstå af sig selv og dokumentationen er en opgave man kan trække som sorteper på sprint mødet. Det er derfor ikke underligt at drømmen om letvægtsarkitektur dokumentation er udbredt.

Letvægtsarkitekturen

Et af de mest trendsættende konsulent huse indenfor agil udvikling, ThoughtWorks, har netop dette på deres Technology Radar. Mere præcist argumenterer de for, at man skal begynde på en såkaldt Lightweight Architecture Decision Record. De skriver i deres seneste Technology Radar:

“Although much documentation can be replaced with highly readable code and tests, in a world of evolutionary architecture it’s important to record certain design decisions for the benefit of future team members and for external oversight. Lightweight Architecture Decision Records is a technique for capturing important architectural decisions along with their context and consequences. Although these items are often stored in a wiki or collaboration tool, we generally prefer storing them in a source control with simple mark up” (p.7)

I stedet for traditionel arkitektur dokumentation går deres forslag på at oprette såkaldt Architecture Decision Records (ADR). Det er versionerede og fortløbende nummererede arkitekturbeslutninger. Indholdet af en sådan ADR er: Titel, Kontekst, Decision, Status, Konsekvenser. Resten af dokumentationen er tilsyneladende tilstrækkeligt ved at skrive “highly readable code and tests”. Det ved vi jo er en tilgang som aldrig fejler (ironi).

Arkitektur dokumentation er altså skåret ned til arbitrært dokumenterede beslutninger, velskrevet kode og test cases. Det er jo et paradigme som passer perfekt til et firma som lever af at levere udvikler konsulent ydelser. Hvis de selv er de eneste, som kan forstå og finde arkitektur dokumentationen, er der jo grund til at ringe til dem ofte, så derfor modviljen mod offentligt tilgængelige tools som wikier.

Man kan så spørge sig selv om, man ville være tilfreds med det, hvis man selv hyrede en en entreprenør til at bygge sit eget hus. Det svarer til at entreprenøren siger at det helt nye er at man ikke skal dokumentere noget i byggeplaner af nogen art. I stedet vil de gemme nogle post it's der beskrev, hvorfor de havde gjort som de gjorde forskellige tilfældige steder i hulmuren. Hvad gør man så når man skal udvide sit hus eller lægge endnu et bade værelse ind?

Udviklerfælden

Dette er et godt eksempel på, hvordan nogle leverandørers anbefalinger er optimeret i mod deres egen forretningsmodel og ikke deres klienter. For klienterne ville have meget bedre gavn af at have transparent dokumentation, som kan bruges til planlægning og forståelse af mange forskellige interessenter, hvor ThoughtWorks kun har brug for, at det er udviklere (og kun udviklerne), som kan forstå dette. Derfor skal letvægtsdokumentationen naturligvis ligge i Github eller lignende esoteriske steder, som med god grund altid er lukket for alle andre end udviklere.

Ved at sikre, at dokumentationen er ad hoc og letvægt, vil der altid være usikkerhed om, hvad der egentlig er lavet, og derfor vil der være brug for at tilkalde udviklerne. På denne måde er smarte nye teknikker faktisk skjulte leverandør lock-ins, som er svære at gardere sig imod.

EA fælden

Men ThoughtWorks er jo ikke helt dumme. De har fat i noget vigtigt og rigtigt, nemlig at arkitektur dokumentation godt kan være mere simpel og letvægts. Desværre ved de ikke noget om arkitektur eller at opbygge langsigtede capabilities. Da de jo lever fra projekt til projekt, kan de af gode grunde også være ligeglade eller faktisk glade jo mere kaotisk dokumentationen er.

Der, hvor de har ret, er, at man hurtigt kan miste modet, hvis man ryger i favnen på den anden gruppe af konsulentsælgende firmaer, nemlig EA konsulenthusene. Når de ruller ind med deres TOGAF plancher og stakke af templates, så er vi røget over i den anden grøft. For her kan der være meget langt til at få bygget noget som helst software overhovedet.

De prøver at få dig overbevist om, at du er langt ude på gyngende grund, og at kun de kender vejen, som naturligvis går igennem dokumentation af hver enkelt bevægelse af hånden på forretningen og hvilken vej hver bit vender på alle servere.

Dette er også en form for leverandør lock-in, for disse leverandører forstår også at sælge EA som en mystisk disciplin, der lover store resultater. Når disse resultater umiddelbart udebliver er det på grund af utilstrækkelig implementering og der må investeres mere.

Den gyldne middelvej

Derfor har jeg lavet min egen letvægts arkitektur, som tilgodeser alle tænkelige behov. Den er baseret på TOGAF, men kun meget løst.

Byg et Architecture Repository - egentlig bare et sted til at samle dokumentation for alt relateret til arkitektur. Beslut hvilken struktur det skal have og hvilke grundlæggende normer for dokumentation der skal være, baseret på hvad du selv synes er rimeligt i din situation. Som minimum er det rart at have versionering og ændringslogs. Hvis du arbejder indenfor en reguleret industri eller et sted, hvor mange forskellige arbejder i det samme systemlandskab, kan det være at det er en fordel at have meget dokumentation. Hvis du laver din mors e-shop til at sælge frugtfarvet gedeuldsgarn, kan du nok slippe af sted med mindre.

Beslut dig for en liste over arkitektur principper - Her er TOGAF formatet til at beskrive og dokumentere principper fint. Disse er meget virkningsfulde, hvis de bliver formuleret korrekt, da de kan informere beslutninger. Sørg for, at de er konsistente.

Beskriv virksomheden - Find beskrivelser af virksomhedens vision fra et eller andet sted. Det kan normalt findes i forretningsplanen, strategien eller et pitch deck i nystartede virksomheder. Find også centrale principper for, hvordan virksomheden fungerer. Dette er afgørende for at gøre rigtigt, fordi hjørnestenen i
Enterprise Architecture i modsætning til softwarearkitektur er at binde systemer til den egentlige forretning.

Beskriv Arkitektur Visionen - Giv en klar overordnet beskrivelse af arkitekturen, du arbejder hen imod på et givet tidspunkt. For en opstartsvirksomhed kan det være 2 års sigt kan være tilstrækkelig, men større virksomheder kan have brug for 5 år horisont eller mere. Arkitekturen vision bør være en oversigt med få eller ingen detaljer. Til dette foretrækker jeg et enkelt kasse diagram i stedet for mere teknisk UML diagrammer. Der kan være flere visioner, da der kan være flere separate områder. Beslut dig for en god måde at dele dem op, og om det er baseret på data-domæner, arkitektur lag, forretningsprocesser eller andet.

Lav en oversigt over arkitektoniske byggesten - Hver separat byggesten, uanset om det er en infrastruktur komponent eller slutbruger applikation, skal katalogiseres. Det vil sige alle programmer og online-tjenester, der er i brug af virksomheden, skal dokumenteres. Dette vil være afgørende længere henne ad vejen, når du for eksempel vil lave en risikovurdering, SLA / OLA, tildele ansvar, gennemføre overvågning, binde arkitektur til forretningsprocesser med henblik på virksomhedens kontinuitet osv. Alle disse ting har brug for at blive koblet op til isolerede byggesten. Mange virksomheder bruger applikationskoder til at identificere disse byggesten. Du skal komme med en proces for tildeling af sådan en unik nøgle til dine softwarekomponenter. Sørg for at koden er enkel og mundret, så de kan indgå som umærkelige koder i den daglige samtale. Du kan altid udvide de oplysninger, der er registreret, men et navn, formål, teknologiplatform og licens oplysninger er et godt sted at starte.

Sørg for at bryde arkitektur ned til forandringstiltag - Det er vigtigt at have en struktureret tilgang til hvordan arkitektur planer bliver ført ud i egentlige projekter. TOGAFs ADM metode er god (i hvert fald konceptuelt) til at gennemføre forandringsinitiativer. Det præciserer faser af arkitektur- og udviklingsarbejdet. Det er en god måde at nedbryde barrieren fra arkitektur plan til kørende projekt. Hvis man er helt overfølsom overfor sådan noget vandfaldsagtigt noget, kan man også overveje Scaled Agile Framework, hvor arkitekturmæssige tiltag bliver brudt ned til epics gennem en architectural runway.

At gøre drømmen til virkelighed

Alle drømmer om at gøre alt overflødig arkitekturdokumentation til letvægt. Med god grund. Intet er værre end overflødig dokumentation. Min oplevelse er dog ikke, at det væsentligste problem i dagens software udvikling at der bliver skrevet for meget dokumentation, nok snarere det modsatte. Grunden til det kan så have noget at føre med urealistisk høje ambitioner om hvad dette skal indebære. Derfor handler det om at gøre dokumentationen præcis så letvægts som muligt, men så heller ikke mere.

Kommentarer (3)
Denny Christensen

Letvægt, ingen tro på at fuld dokumentation kan opnås og alligevel noget bedre end altid at rode med kode eller ringe til tidligere medarbejdere...

Jeg er enig i niveauet og så skal man, naturligvis, lige huske at vise 'alle' at det er til at komme lidt hurtigere i gang og involvere lidt færre mennesker end hvis der slet ingenting var.

TOGAF og lignende er glimrende hylder at plukke fra, så længe man ikke ukritisk tager frameworket som et færdigt stykke metodik.

Jesper Frimann

Det skulle da lige være manglende dokumentation.

Niveauet af IT-dokumentation er meget afhængig af, hvilken branche man er i. Man kan formulere det... hvor vigtigt er IT for din virksomhed. Typisk kan man måske sige, at jo mere IT, er en integreret del af virksomheden core business, jo højere krav til dokumentationen.

Men dokumentationen skal stadig være brugbar og helst ikke for tung.

Nu bliver Anders Lisdorf meget specifik med den 'Den Gyldne Middelvej' (tm).
Jeg synes der er nogen åbenlyse mangler, hvilket nok skyldes min baggrund i IT-Service branchen.

F.eks. er en organisatorisk plan over hvor viden, kompetencer og ansvar for forskellige IT områder befinder sig i organisationen, noget af det aller vigtigste. Der er rigtig meget, i rigtig mange virksomheder, der er dokumenteret i 'Grey Matter'. Og man skal vide 'Who is the goto guy' (m/k).

Og hvis disse 'Grey Matter' dokumentations/skills/process repositories forsvinder fra virksomheden kan det potentielt have katastrofale følger økonomiske for virksomheden. Vi kender alle legacy løsninger og systemer, som er forretnings kritiske men hvor 'Mortensen' er holdt op, og derfor tør ingen røre ved det.

Ud over dette, skal man huske på at Enterprise Arkitektur er det hele. Derfor vil man f.eks. skulle forholde sig andre end den rene IT professions metoder, standarder og kultur. Og dette skal man kunne absorbere og forholde sig til.

// Jesper

Peter Sjoelin

Hej Anders,

Jeg er glad for at høre, at du med dine anbefalinger læner dig op ad det tankegods som Martin van den Berg med flere gjorde i værket "Dynamic Enterprise Architecture: How to make it work".

En ting som er værd at tage med i forhold til dine anbefalinger at enterprise arkitektur (og IT-arkitektur) kun anvendes i de situationer, hvor der er tale om planlagt udvikling.

Du kan eventuelt læse mere her:

Dynamisk Enterprise Arkitektur i praksis: https://enterprisearkitekten.com/2012/08/02/dynamisk-enterprisearkitektu...

og

Trefordele og ulemper ved at anvende DYA: https://enterprisearkitekten.com/2011/12/22/tre-fordele-og-ulemper-ved-a...

Med venlig hilsen

Peter Flemming Teunissen Sjølin
EnterpriseArkitekten.com

Log ind eller Opret konto for at kommentere