Målet med dokumentationen

Dokumentationen ska ge läsaren god förståelse för programmets arkitektur och design.
Antag att läsaren har samma kunskap som de som skrivit prototypen förutom att hon/han inte vet något om programmet.
Dokumentationen ska ge läsaren så god förstålse för programmet att det går att ändra och utöka det utan att bryta mot den fastställda arkitekturen.
Tänk på vad du själv skulle vilja veta om du skulle ta över underhållet av programmet.

Prototypen ingår i dokumentationen

Dokumentationen består av två delar:

En prototyp som består av en första version av programmet under utveckling. Den ska innehålla tillräckligt mycket kod för att förklara arkitekturen/designen. Observera att det ska vara kod av produktionskvalitet. Den ska vara testad, kommenterad, strukturerad osv på det sätt som det färdiga programmet ska vara.
En skriven dokumentation (kallas ofta arkitekturdokument) som förklarar arkitektur/design. De följande sidorna förklarar vad den ska innehålla.

Dokumentationen måste vara klar och tydlig

Det viktiga är att dokumentationen så enkelt och tydligt som möjligt förklarar arkitekturen.
Det finns många mallar för arkitekturdokument. Kom ihåg att de måste anpassas! De är bra att hämta inspiration från men de innehåller mycket ofta avsnitt som inte behövs. Ta inte med sådana. Kanske saknar de även avsnitt som faktiskt behövs.

Vad kan arkitekturdokumentet innehålla?

Det är populärt att dela in dokumentet i olika vyer. Med vyer menas då helt enkelt olika avsnitt, där vart och ett förklarar olika områden. Med områden menas inte paket eller lager, tvärtom avhandlas hela programmet i varje vy. Vanliga vyer är:
- Funktionalitet, förklarar vad användaren kan göra med programmet.
- Logisk uppdelning, förklar till exempel hur programmet är uppdelat i lager och vilka mönster som använts.
- Säkerhet, förklarar sådant som inloggning, rättigheter, kryptering och loggning.
- Datalagring, förklarar databasens struktur och hur datat översätts mellan databasen och programmet.
- Fysisk uppdelning, förklarar hur programmet är uppdelat på olika datorer och processer.
- Implementation, beskriver programmets filer och hur dessa ska hanteras av användaren.
Det är förstås helt ok att strunta i vyer som inte behövs, och även att vid behov lägga till andra vyer.
Hur förklaras programmet? En bra metod är att börja med att skriva löpande text och sedan förtydliga texten med utdrag ur källkoden, uml-diagram, bilder på användargränssnittet och andra bilder. Saknas löpande text är det inte ett lättförstått dokument. Finns det inga bilder eller kodutdrag som illustrerar texten är det knappast heller lättförstått.

Avsnittet Funktionalitet

Avsnittet ska visa varför programmet finns.
Förklara vad användaren kan göra med programmet
Förklara inte all funktionalitet, bara den viktigaste.
Ange in- och utdata för viktiga systemoperationer.
Illustrera gärna med bilder på användargränssnittet. I labb 3 har programmet inget grafiskt användargränssnitt, visa då i stället en skärmdump av en exekvering i ett kommandofönster.

Avsnittet Logisk uppdelning

Avsnittet ska förklara programmets arkitektur och design.
Förklara vilka lager som finns.
Rita ett interaktionsdiagram (dvs sekvens- eller kommunikationsdigram) som går genom alla lager. Kom ihåg att förklara det! Ta inte med interaktionsdiagram för all funktionalitet, bara tillräckligt mycket för att förklara hur de olika lagren är uppbyggda och hur de kommunicerar med varandra.
Om det finns någon del av designen som är speciellt klurig kan den förklaras med text och interkationsdiagram i ett eget delavsnitt.
Det kan vara en bra idé att ta med utdrag ur koden, antingen i stället för interaktionsdiagram eller tillsammans med dem. Välj i så fall noga ut vilka kodavsnitt som ska vara med, inga långa koddumpar. Det kan också vara bra att rensa upp lite i koden och bara visa det viktigaste. Till exempel kan undantagshantering tas bort. Ange i så fall i texten att koden inte är komplett. Kod ska den placeras i en figur med figurtext, tydligt avskilld från resten av texten.
Ange viktiga mönster som använts.
Ta med domänmodellen om du anser att den förtydligar. Kom ihåg att den i så fall ska förklaras också, visa aldrig en bild utan förklarande text.
Förklara hur det är tänkt att ny funktionalitet ska läggas till. Syftet med det är att designen inte ska förstöras i framtiden när någon annan utvecklare lägger till funktionalitet. Ta gärna med ett exempel där ny funktionalitet läggs till.
Antag att läsaren har ungefär samma kunskaper som du själv, men inte vet något om programmet i fråga. Det är alltså inte nödvändigt att, mer än möjligtvis ytterst kortfattat, förklara välkända mönster som tex controller. Fråga dig själv vad du skulle behöva få reda på för att förstå programmet så bra att du skulle kunna ta över underhållet av det.

Avsnittet Säkerhet

Avsnittet ska förklara alla lösningar på säkerhetsproblem. Ange också om något problem är känt men inte löst.
Exempel är inloggning, rättigheter, kryptering och loggning.
Om programmet inte innehåller någon säkerhetshantering kan det ändå vara en bra idé att ta med det här avsnittet och skriva att ingen hänsyn tagits till säkerhet. På det viset blir det tydligt att säkerhetshanteringen avsiktligt utelämnats, läsaren slipper fundera på om det finns någon odokumenterad säkerhet.

Avsnittet Datalagring

Avsnittet ska förklara hur data lagras och hur programmet kommer åt datat.
Ofta används en databas, men alla program har någon form av data. Om en databas inte används kanske datat sparas i vanliga filer. Kanske finns det inte något persistent (bestående) data alls, datat finns bara i programmets minne och försvinner när programmet avslutas. Oavsett vilket som är fallet finns det data i programmet och alltså anledning att skriva om datalagring i arkitekturdokumentationen.
Avsnittet ska också förklara hur datalagret anropas, dvs hur programmet läser och skriver data. Ilustrera gärna detta med interaktionsdiagram och/eller utdrag ur koden.

Avsnittet Fysisk uppdelning

Avsnittet ska förklara hur programmet är uppdelat på olika datorer och processer samt hur dessa kommunicerar med varandra.
Beskriv vilka olika fysiska noder (datorer) som finns och vilka program som körs på dessa (tex webserver, databasserver). Beskriv också hur dessa kommunicerar med varandra.
Illustrera med ett deploymentdiagram.
Till labb tre kan du ta med åtminstone två noder, datorn programmet körs på och skrivaren som skriver ut kvittot.

Avsnittet Implementation

Avsnittet ska förklara vilka filer programmet består av. Det ska också förklara vad användaren ska göra med dessa filer, tex för att installera och starta programmet.
Förklara hur programmet installeras, dvs exakt vad användaren får (tex en zip- eller rar-fil) och hur användaren ska packa upp dessa, dvs var filer ska placeras på datorn.
Förklara vad de olika uppackade katalogerna innehåller.
Ange om användaren måste installera något annat (tex Java) för att kunna använda programmet. Ange i så fall vilken version som krävs.
Ange eventuella krav på användarens dator, tex hur mycket minne den måste ha och på vilka operativsystem programmet kan installeras.
Förklara exakt hur användaren startar programmet. Ange alla steg från att packa upp programmet tills det är igång. Prova att följa instruktionerna och kontrollera att det stämmer.
Om användaren får källkoden, ange också exakt hur programmet kompileras. Ange om det exekverbara programmet är kompilerat från den inkluderande källkoden eller inte.

Avsnittet Problem

Avsnittet ska ta upp speciellt kluriga problem som dykt upp under utvecklingen.
Vad som är speciellt klurigt är förstås svårt att avgöra. Fråga dig om det i det övriga dokumentet är något som är underförstått , om det är något läsaren kan missförstå eller förväntas ha insett. Ta hellre upp för många problem än för få.
För varje problem, ange problem, lösning och förkastade lösningar. Om det framgår att de förkastade lösningarna beaktats och varför de inte godkänts kan det spara mycket arbetet i framtiden. Saknas denna information finns risken att de förkastade lösningarna börjar övervägas igen vid flera tillfällen.
Illustrera med tex kodutdrag, uml-diagram eller bilder på användargränssnittet, beroende på var problemet fanns.
Hitta inte på problem, men tveka inte att ta upp de som faktiskt funnits.

Exempel på ett arkitekturdokument

Dokumentet kan innehålla följande:

Förstasida med tex författare, programmets namn, dokumentets namn (dvs arkitekturdokument) och företagets namn.
Revisionshistorik.
Innehållsförteckning.
Inledning som mycket kortfattat beskriver programmet och varför det utvecklats.
Funktionell vy, se Avsnittet Fuktionalitet.
Logisk vy, se Avsnittet Logisk uppdelning.
Säkerhetsvy, se Avsnittet Säkerhet.
Datavy, se Avsnittet Datalagring.
Deploymentvy, se Avsnittet Fysisk uppdelning.
Implementationsvy, se Avsnittet Implementation.
Problem, se Avsnittet Problem.
Referenser, möjliga exempel inför labb tre är Larman, föreläsningsanteckningarna och en websida varifrån Java kan laddas ner.

Vanliga misstag

Inga eller irrelevanta bilder

Kanske började vi med att skriva texten och orkade sedan inte rita bilder. En variant på att då strunta helt i bilder är att leta upp några färdiga på webben. Dessa har förmodligen ganska lite med texten att göra, i alla fall förtydligar de den inte. Sådana bilder är sämre än inga alls eftersom läsaren måste ägna tid åt att fundera på vad de betyder.

För många och/eller för omfattande UML-diagram

Detta blir lätt fallet om vi låter ett UML-verktyg automatgenerera diagrammen. Gör vi det kommer det ofelbart med irrelevanta detaljer. Diagrammen blir också alldeles för stora. UML-diagram är mycket bra för att förtydliga texten men de måste ritas med lite eftertanke. Det viktiga är vad vi vill att ett diagram ska visa och om det verkligen visar just det. Automatgenererade diagram är aldrig bra om det inte editeras för hand.

Ingen eller väldigt lite text

Så blir det lätt om vi börjar med att rita avancerade UML-modeller och sedan inte orkar förklara dem.

Vanliga misstag, forts

Automatgenererade UML-diagram

Se avsnittet "För många och/eller för omfattande UML-diagram" ovan.

Inga bilder på användargränssnittet

Sådana är till stor hjälp när det handlar om att förklara programmets funktionalitet. Överallt där det finns text som talar om vad användaren gör med programmet bör det finnas bilder den vy användaren ser.

Inga kodutdrag

Inbland är det bättre att förtydliga texten med källkod än med UML. Det gäller främst när texten handlar om något som är svårt att programmera, inte när det handlar om att förklara programmets struktur. Om det är en komplicerad design kan det dock vara bra att både rita ett UML-diagram och ta med en kodsnutt.

Vanliga misstag, forts

Inga interaktionsdiagram

De flesta (inklusive mig) tycker det är jobbigare att rita interaktionsdiagram än att rita klassdiagram. Interaktionsdiagram är dock viktiga eftersom de oftast förklarar bättre än klassdiagram. Finns det inga eller få interaktionsdiagram i arkitekturdokumentet är det stor risk att vi ritat klassdiagram av ren slöhet.

Irrelevant information

Det är bara alltför vanligt att arkitekturdokumentation innehåller irrelevant information. Det beror ofta på att författaren följt en färdig mall och tagit med för mycket ur den. Mallar är ofta på tok för omfattande. Den överflödiga texten beskriver ofta läsare, författare, företag, projektgrupper och liknande. Gärna finns dessutom ungefär samma information på flera ställen i dokumentet.

Dokumentation ersätter inte kommunikation

Hur bra akritekturdokumentet än är kan det aldrig ersätta en dialog.
För att lyckas med ett projekt är det extremt viktigt att alla försöker upprätthålla bra relationer med varandra och strävar efter att tillsammans föra projektet framåt.
Detta gäller på alla nivåer, till exempel mellan olika utvecklare, mellan utvecklare och kunder, mellan utvecklare och användare samt mellan utvecklare och projektledare.