Introduktion

Nedan följer en genomgång av de dokument som man kan ha till hjälp under ett projekt. Det listade innehållet är ett förslag och det kan givetvis förändras beroende på projekt.

Projektgruppen bör bestämma en grundläggande mall och format för sin dokumentation, vad som behövs är upp till projektgruppen att avgöra. Några kanske klararar sig med textformat, andra HTML (en enkel hyperlänkad struktur har många fördelar) eller word.

Tänk på att göra förfarandet med dokumentationen så enkel som möjligt så att ni orkar hålla den uppdaterad.

Varför dokumentation?

Dokumentation är helt enkelt ett sätt att kommunicera med olika parter som Kund, Slutanvändare, Projektmedlemmar, Ledning etc. etc. Den effektivaste formen av kommunikation är ansikte mot ansikte i avseende att snabbt kunna kommunicera ett budskap. En skriftlig dokumentation har dock flera andra fördelar:

• Tidsbeständig: Man behöver inte komma ihåg budskapet själv hela tiden.
• Masskommunikation: Flera personer kan läsa en skriftlig dokumentation samtidigt.
• Rum: Personerna behöver inte befinna sig på samma plats för att få ett budskap.
• Lågteknologiskt: Det krävs ingen speciellt avancerad teknologi för skriftlig kommunikation, papper och penna i det absolut enklaste fallet
• Bilder: En bild säger mer än tusen ord…

Det finns naturligtvis även nackdelar med skriftlig dokumentation, som man ska sträva efter att minimera.

• Missförstånd: Kan den som läser budskapet förstå det som det är tänkt? Tänk på vem som ska läsa dokumentet och anpassa texten efter det, förklara ord i en ordlista.
• Tungrott: Konstiga mallar och ordbehandlingsprogram stjälper ibland mer än de hjälper. Se till att dokumentationen är lättarbetad.
• Fel fokus: Ibland misslyckat projekt för att de har koncentrerat sig för mycket på dokumentation och på fel dokumentation men inte lyckats leverera en fungerande produkt. Se till att den dokumentation ni gör är till hjälp för projektet.
• “Dokumentatör”: I vissa projekt råkar någon av olika anledningar bli den som handhar all eller den största delen av dokumentationen. Detta skapar ofta en klyfta mellan dokumentationen och det verkliga systemet (se nedan) och kan även splittra projektgruppen i en utvecklande del och en administrativ del. Se till att alla i projektgruppen arbetar med dokumentationen och låt den bli en levande del av projektarbetet. T.ex. när ett krav implementeras så är det naturligt att detaljera kravet ytterligare samt skriva ett testfall.
• Inte uppdaterad: Det är väldigt förvirrande om dokumentationen säger en sak och systemet beter sig på ett annat sätt. Missvisande dokumentation är ofta värre än ingen dokumentation.

En slutsats är att för att dokumentation ska vara till nytta så måste man se till att den är enkel att arbeta med och att man bara dokumenterar sådant som är absolut nödvändigt samt att alla hjälper till att hålla dokumentationen uppdaterad och levand.

Projektplan (obligatoriskt)

Projektplanen har till syfte att kommunicera de grundläggande avgränsningarna i projektet i form av tid, budget och resurser samt hur dessa är organiserade. Tilltänkta läsare är Beställare, Ledning och Projektdeltagare.
I projektplanen och tillhörande dokument (Iterationsplaner och Risklista) ska man löpande kunna följa arbetets gång och enkelt avgöra om projektet håller sig inom uppsatta ramar samt vilka avsteg som gjorts.

Förslag på innehåll:

• Projektnamn
• Kund med kontaktuppgifter
• Uppdragstagare med kontaktuppgifter
• Bakgrund till projektets uppkomst
• Syfte med projektet
• Projektets övergripande mål
• Resursplan
• Tidplan för projektet, med milstolpar för deadlines, beakta speciellt hårda deadlines som inte går att flytta på
• Storleksuppskattningar av systemet, t.ex. antal rader kod, antal klasser, antal use cases, antal funktioner, antal sidor etc.
• Kommunikationsplan
• Projektorganisation
• Ansvarsfördelning

I början är projektplanen ofta ganska grov och opålitlig när man går in i Constructionfasen så ska dock projektplanen vara tillräckligt solid och större avsteg kan anses som allvarliga.

Risklista (obligatoriskt)

Risklistan har till syfte att säkerställa ett lyckat projekt genom att synliggöra och lyfta fram risker i projektet samt arbeta fram en plan för hur dessa skall hanteras. Risker är helt enkelt händelser som om de inträffar påverkar projektet negativt. Risker är således en viktig input till iterationsplaneringen, där varje iteration syftar till att minska sannolikheten och/eller konsekvensen för en eller flera risker.

Risklistan bör innehålla:

• Top 5 risker i prioritetsordning
• Riskspecifikationer
• Id
• Risknamn
• Beskrivning
• Sannolikhet (1-5), Konsekvens (1-5), Prioritet: Sannolikhet * Konsekvens
• Bevakningsstrategi, hur kan vi bevaka denna risk, vem är ansvarig?
• Konsekvensstrategi, kan vi på något sätt minska konsekvensen av risken?
• Sannolikhetsstrategi, kan vi på något sätt minska sannolikheten att risken inträffar?

Risklistan skall kontinuerligt betas av och uppdateras. Gamla omhändertagna risker skall prioriteras ned, nya risker skall föras in. När man går in i Constructionfasen får inga allvarliga risker finnas ohanterade.

Iterationsplan (obligatoriskt)

Iterationsplanen är en detaljerad plan för en iteration. Den upprättas med input från Risklistan, Projektplanen och återkoppling från kunden.

Iterationsplanen bör innehålla:

• Analys av föregående iteration med “burndown chart”
• Tidsrapport – arbetad tid i iterationen, per uppgift och per projektdeltagare
• Nya Risker
• Mål för iterationen (vilka risker skall hanteras, vilka krav skall testas och levereas, vem arbetar med vad)
• Skattad sprint backlog

Ofta behöver man vara ganska konkret i sin målbeskrivning för att man ska kunna avgöra om målet är uppfyllt eller inte. “Tråkiga” uppgifter bör tilldelas ett tydligt ansvar.

Vision (obligatoriskt)

Syftet med visionen är att på ett enkelt sätt beskriva problemet som projektet avser lösa, vem/vilka som är behjälpta av att få problemet löst samt vilka grundläggande egenskaper systemet måste uppvisa för att lösningen skall betraktas som bra (detta är baskraven/eng. features). Visionen skall dock inte beskriva hur detta skall gå till, vare sig tekniskt eller organisatoriskt. Tilltänkta läsare är i stort sett alla inblandade i projektet, en gemensam vision är en av de viktigaste punkterna i ett projekt och ett ett krav för att passera inception fasen.
Visionen gör att alla kan sträva åt samma håll utan att beskriva onödiga detaljer. Visionen kan även vara en viktig input till t.ex. marknadsavdelning.

Visionen bör innehålla:

• Bakgrund och problembeskrivning
• Användargrupper
• Intressenter
• Liknande/Konkurrerande system
• Individuellt numrerade baskrav: Ett baskrav är ett krav på en väldigt hög nivå och innehåller inga detaljer. Sammantaget så skall baskraven lösa problemet i problembeskrivningen och man ska fokusera på det som gör den egna lösningen unik med hänsyn till liknande/konkurrerande lösningar.

Kravspecifikation (obligatoriskt)

Kravspecifikationen kan vara ett eller flera dokument beroende på projektets behov.
Syftet med kravspecifikationen är att tydligt visa vad systemet skall göra för att uppfylla baskraven. På detta sätt kan kravspecifikationen ses som en detaljering av baskraven, kraven skall vara såpass detaljerade att de går att implementera och testa. Kravspecifikationen arbetas med och detaljeras löpande under projektets gång ofta i samarbete med slutanvändare av systemet.

Kravspecifikationen bör innehålla:

• Begränsningar, finns det något som begränsar hur vi kan designa eller implementera systemet. T.ex. ett viss språk, en viss teknik etc.
• Projektkrav, finns det några krav på projektmodell, struktur eller dokumentation?
• Kvalitetskrav, vilka krav på t.ex. prestanda, användarvänlighet och säkerhet finns det?
• Funktionella krav, vilka funktioner skall systemet ha? Ofta i form av användningsfall.

Att dokumentera och hantera krav är mycket svårt och det finns många metoder för detta. En teknik för kravdokumentation som blivit populär i framförallt interaktiva system är användningsfall och user stories. Andra sätt är enkla listor med “Systemet skall”, tabeller och tillståndsmaskiner kan vara bra för regelbaserade system.

Det är viktigt att ni väljer de kravhanterings-tekniker som krävs för erat projekt. Generella krav på krav är:

• Unikt id
• Tydligt förklarande namn
• Referenser (vilket baskrav hjälper detta krav till att uppfylla, vem har skrivit, vem är källan)
• Status (implementerat, testat, ogiltigt, …)
• Tydlig beskrivning av kravet som går att förstå
• Testbart, ni måste kunna testa kravet hur skall det gå till, referens till testfall. Att skriva testfall först kan vara en fördel. Var särskilt uppmärksamma på hur kvalitetskrav skall testas.
• Icke motsägelsefullt, två krav får inte säga emot varandra.
• Prioritet
• Beroenden till andra krav

Ordlista

Syftet med ordlistan är att föklara termer och begrepp så att missförstånd kan undvikas och att samla dessa förklaringar på ett ställe.

Mjukvaruarkitektur/Teknisk Dokumentation (obligatoriskt)

Syftet med mjukvaruarkitekturen är strukturera mjukvaran så att kraven enkelt kan implementeras och att visa på strukturens konsekvenser. För att göra detta så väljer man ut ett fåtal krav och implementerar dessa enligt den bestämda strukturen, dessa utvalda krav brukar kallas för “arkitekturellt signifikanta krav”. Att välja dessa krav är inte så lätt, man bör särskilt beakta kvalitetskrav och man skall ha med krav som behandlar alla delar av den valda strukturen. Målet är att övrig funktionalitet “enkelt” skall kunna implementeras givet strukturen och de implementerade arkitekturellt signifikanta kraven.
Dokumentationsmässigt så består arkitekturen av:

• Lista arkitekturellt signifikanta krav och motivera varför just dessa krav valdes
• Beskrivning av vald struktur och hur de arkitekturellt signifikanta kraven implementerats mha strukturen. Beskrivs med text, klass- och interaktionsdiagram. Här kan det också vara viktigt att inte bara beskriva logiskt, utan även vart filer ska placeras, vilka api:er/bibliotek/komponenter som ska användas. Målet är att en ny utvecklare snabbt ska komma in på banan och kunna börja implementera nya features på ett bra sätt.
• Strukturens konsekvenser, vilka är strukturens fördelar, vilka är dess nackdelar.

Det är viktigt att alla kan förstå den valda arkitekturen och att man inte känner någon oro för att något eller några viktiga krav ej går att implementera utan att förändra strukturen. Att ha en implementerad, testad och levererad arkitektur är ett krav för att få avsluta elaboration fasen.

Ibland har man inte så mycket val vad gäller arkitektur, kunden kanske har specifika önskemål, det finns standarder för den typ av applikation man gör etc. Det kan då vara viktigt att dokumentera hur dessa fungerar och hur projektspecifika delar är tänkta att lösas.

Teknisk dokumentation är allt som kan tänkas behövas i en underhållssituation, t.ex. för att kunden ska kunna implementera funktionalitet som ni inte hinner eller kring hur systemet kan byggas ut, driftsättas etc.

Testspecifikation (obligatoriskt)

Testspecifikationen listar helt enkelt de testfall som skall genomföras för att testa ett eller flera krav, samt beskriver allmänt vad som krävs för att genomföra olika systemtester, t.ex. installation/konfiguration av testmiljö. Testfallen kan antingen vara en del av testspecifikationen eller separata dokument i sig.
Testspecifikationen bör innehålla:

• Allmänna testprocedurer
• Systemtester med referenser till testfall
• Testfall

Ett systtemtest är helt enkelt en lista av tesfall med syfte att testa något specifikt, t.ex. ett baskrav, särskild vikt bör läggas vid kvalitétskrav då dessa ofta är både avancerade och tidskrävande att testa.

Ett testfall bör innehålla:

• Referens till vilket eller vilka krav som testas
• Ev. förkrav eller speciell konfiguration av testmiljön.
• Indata specifikation, d.v.s. vilken indata skall användas
• Utdata specifikation, d.v.s. vilken utdata förväntas
• Steg för steg beskrivning hur testfallet genomförs, optimalt är att kunna referera till ett scenario i kravspecifikationen
• Ev. kontroll av efterkrav, t.ex. hur man kontrollerar att databasen är uppdaterad.

Målet är att man skall kunna ge ett testfall till någon som inte är insatt i systemet och de ska kunna avgöra om testet är lyckat eller inte. Glöm inte heller att testning inte enbart är ett mekaniskt arbete, försök att vara kreativa i era testfall och hitta kluriga situationer som ni inte tänkt på.

Testning över lag är ett svårt område och det kan alltid finnas buggar i ett system. Arbeta kontinuerligt med testningen, prioritera testning av riskfyllda delar och vänta inte med testning till slutet!

Beakta också den mer generella testning som genomförs av kund och slutanvändare. Dessa tester kan vara en viktig input och kan omvandlas till nya testfall.

Testrapport (obligatoriskt)

Testrapporten är ett enkelt dokument som anger resultatet av ett systemtest eller samlar återkoppling från ett mer allmänt test av en slutanvändare eller kund. Testrapporterna blir en viktig input till iterationsplanering, risklistan och måluppfyllning.
Testrapporten bör innehålla:

• Datum
• Tydlig referens till vilken version av systemet som testats. Viktigt!
• Tydlig referens till vilket systemtest som körs
• Tydlig beskrivning av testmiljö
• Lista av testfall och “pass/fail” status samt ev. kommentar
• Analys med en beskrivning av känslan av systemet, känns det stabilt, skakigt, vilka delar är bra, vad behöver förbätras.

Tidsrapport (obligatoriskt)

Tidsrapporten innehåller information kring varje projektdeltagares tid i projektet per iteration och aktivitet samt vettiga översikter. Tidsrapportering görs individuellt och per iteration, projektledaren sammanställer.
Tidsrapporten bör innehålla:

• Totalt arbetad tid i projektet per person
• Totalt arbetad tid i projektet per iteration
• Totalt arbetad tid i projektet per person per iteration

Att klara av att rapportera sin tid är ett obligatoriskt moment i kursen. Rapporter i efterhand godkännes ej! Slarva inte med detta!!