Mjukvaruutveckling som profession har förändrats snabbt de senaste 20 åren. Vi har gått igenom stora skiften såsom t ex cloud, test-driven utveckling och container baserad-teknik, för att nämna några. Men lite har hänt kring hur vi faktiskt dokumenterar våra lösningar och vår arkitektur. Kanske är det för att det ses som tråkigt? Något man bara måste göra på slutet av projektet för att det är avtalat så. Samtidigt vet vi ju vikten av effektiv dokumentation av en lösning. Inte minst för en långsiktigt fungerande förvaltning, eller för den delen för att man själv skall förstå en lösning tre månader senare.
Men låt oss ta ett steg tillbaka. Vad menar man med dokumentation av en lösning?
VISUELL VS. TEXTUELL DOKUMENTATION
När vi tänker på dokumentation av en lösning tänker nog många av oss på att fylla i ett Word-dokument. Har man riktigt tur finns det ett antal fördefinierade rubriker man kan fylla i.
Men det är ju få saker som är så mentalt ansträngande som att öppna ett mer eller mindre blankt dokument, veta att man behöver lägga timmar på fylla i det och att det sedan med största sannolikhet inte kommer att läsas av någon…
Om du istället föreställer dig att du på enklast möjliga sätt ska beskriva en lösning för en kollega. Troligtvis kommer du då inte att börja med text. Förmodligen kommer ni ställa er framför en whiteboard och börja rita boxar med enkla pilar mellan. Visuella diagram är det absolut effektivaste sättet för oss människor att kommunicera komplexa sammanhang, det gäller också när vi ska beskriva lösningar och arkitektur.
Så varför använder vi inte diagram oftare när vi skall dokumentera lösningar och arkitekturer?
DIAGRAM OCH NOTATION
En av anledningarna till att vi historiskt inte använt oss mer av diagram för att beskriva större arkitekturer och lösningar är att det är ganska enkelt att börja med. Men det blir komplicerat efter ett tag. Utan en modell och en notation blir det snabbt rörigt och svårt att följa.
Unified Modelling Language (UML) känner många igen. Det var en lösning på ovan problem som beskriver en notation för när olika boxar, figurer, pilar, pilhuvuden, färger etc skulle användas och vad det skulle betyda. Problemet med UML var dock att den som notation snabbt blev komplicerad. Det finns veckolånga kurser som bara syftar till att lära sig UML. Något de flesta av oss kände var fel och var ointresserade av.
C4-modellen består av ett antal nivåer av diagram där man börjar med att beskriva större sammanhang som man sedan kan zooma in i. Utöver det innehåller modellen en väldigt simpel notation som mer eller mindre bara beskriver hur man skall använda boxar och pilar dem mellan. På många sätt som hur man skulle ritat upp en lösning på ett whiteboard. Modellen har blivit väldigt populär världen över och allt fler organisationer har adopterat dem för att beskriva sina lösningar och arkitekturer.
FÖRDELAR MED C4-MODELLEN
På Kazoku har vi allt mer anammat C4-modellen. Det ger oss möjlighet att snabbt och effektivt dokumentera en lösning. De olika nivåerna i modellen ger oss också en större möjlighet att kommunicera med både tekniska och icke-tekniska användare av de lösningar vi skapar.
Dokumentation av mjukvara har historiskt sett varit fokuserat på tekniska detaljer och har främst varit ämnad för utvecklare. Det har ofta varit få förunnat att förstå helheten, hur allt sitter ihop. Med C4-modellen gör det möjligt för samtliga intresserade att se hur de olika lösningarna faktiskt fungerar tillsammans och hur lösningen inom organisationen flödar.
För oss på Kazoku är det viktigt att både våra medarbetare och våra kunder känner att vi använder deras tid så effektivt som möjligt för att nå bästa resultat. C4-modellen är det mest effektiva sättet vi har hittat för att dokumentera lösningar.
VERKTYG FÖR C4
Vi har valt att jobba med Revision för att dokumentera våra lösningar. Revision stödjer C4-modellen fullt ut och ger oss samtidigt möjlighet att snabbt och säkert dela våra diagram både internt, inom projektet och till övriga intressenter. Med Revision skapar vi en tillgänglig och effektiv hub för vår dokumentation. Från hubben kan vi sedan dela dokumentation till olika applikationer och plattformar. Revision har flera inbyggda funktioner för att dela diagram effektivt.
INTRESSERAD AV HUR DU KAN DOKUMENTERA DINA LÖSNINGAR?
Vi på Kazoku IT är otroligt nöjda över att vi valde Revision som verktyg för dokumentation, och det är även våra kunder. Att äntligen ha hittat ett verktyg som förenklar dokumentationen är vi väldigt tacksamma för. Är ni också intresserade av Revision? Hör av er till richard@revision.app eller besök https://revision.app/ för mer information.
