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.

GitHub Wiki

Dokumentationen skall uteslutande presenteras via dit repros Wiki-sidor. Ett exempel på struktur tillsammans med beskrivande texter hittar du i kursens exempelrepositorie.

Vill du veta mer om hur man arbetar med GitHub-wiki så kan du läsa om det här: https://help.github.com/articles/about-github-wikis/

Observera att wikin i sig är ett eget repo så att du kan enkelt clona repot och arbeta med det lokalt om du så önskar, eller så använder du gränssnittet via GitLab. All dokumentation skrivs alltså i md-format.

Tänk på att göra förfarandet med dokumentationen så enkel som möjligt så att du orkar hålla den uppdaterad. Tänk också på att det är uppmuntrat att förändra det som inte funkar i dokumentationen under projektets gång.

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 levande.

Syftet med visionen är att på ett enkelt sätt beskriva problemet som projektet avser lösa, vem/vilka som är behjälpta av denna lösning samt de grundläggande egenskaperna som gör lösningen unik. 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. 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
• Beskriv det problem systemet skall lösa, alternativt det behov eller den möjlighet som finns med det nya systemet.
• Användar/mål-grupper: Beskriv de tilltänkta användarna, ju mindre generell din beskrivning är desto enklare att bygga en bra applikation.
• Marknad
• Beskriv konkurrerande och liknande system. Vad gör dessa unika, vilka svagheter respektive styrkor har de, vilken målgrupp vänder de sig till? Försök att tänka brett och generellt (det kanske inte finns något annat system som är exakt samma som det du tänker göra); t.ex. hur löser användarna det problem du tänkt lösa i dagsläget?
• Baskrav/Egenskaper/Features/Unique Selling Points Ett baskrav är ett krav på en hög nivå och innehåller inga detaljer, detaljerna kommer snarare i kravspecifikationen. Baskraven får gärna vara säljande, lyft fram det som gör din applikation bra, spännande, unik etc. Det är ingen mening med att lista “självklar” funktionalitet som t.ex. att “Användaren ska kunna logga in” (detta hör snarare hemma i kravspecifikationen). Sammantaget så skall baskraven lösa problemet i problembeskrivningen för den tilltänkta målgruppen på ett för marknaden unikt sätt.
• Teknik I detta projekt för vi även in ett avsnitt kring tekniker du tänkt använda dig av, då detta är en viktig punkt i dessa projekt. Tekniker kan väljas utifrån tidigare erfarenhet, att man vill testa eller lära sig något, industristandard, tillgänglighet, etc. Teknik kan vara alltifrån val av programmeringsspråk, speciella api:er, ramverk, hårdvaruplattformar, servermjukvaror etc.
• (Ditt namn och program du läser)

Sprint backlog (iterationsplan) är en detaljerad plan för en iteration, i detta fall en vecka. Den upprättas med input från t.ex. Risklistan, Kravspecifikation, Vision, Testrapport och återkoppling från kund/slutanvändare. Denna plan uppdateras och skattas kontinuerligt under iterationen/sprinten. En grafisk status (burndownchart) kan göras om det tillför någon intressant information. Då iterationsplanen och framför allt tidsskattningar och burndownchart skall hållas uppdaterade kontinuerligt så är det ganska smidigt att antingen dela iterationsplanen i två dokument (ett för text och ett kalkylark) eller bara ha det i ett kalkylark. Att klara av att rapportera sin tid är ett obligatoriskt moment i kursen. Rapporter i efterhand godkännes ej! Slarva inte med detta!!

Din sprint backlog bör innehålla:

• Analys av föregående iteration; en kort text kring vad som gick bra och vad som inte gick så bra.
• Tidsrapport – skattad vs. verklig tid för varje mål, totalt arbetad tid i iterationen och projektet.
• Mål för iterationen i form av nedbrutna och tidsskattade krav från kravspec.
• Burndownchart – ej obligatoriskt

Enkelt exempel

Sprint backlog v4 Analys av föregående iteration. Man kan nu göra inlägg i bloggen och texten i dessa kan formateras. Dock tog det lite längre tid än förväntat (framförallt valideringen) och därför har funktionaliteten för likes flyttats fram till denna vecka. Hade även lite problem med att få leveransen att fungera till driftsmiljön, men det visade sig vara ett lösenord till databasen som var fel, så jag ska nu implementera en miljövariabel på produktionsservern och på den lokala servern.

Tidsrapport

Product backlog (Kravspecifikationen) kan vara ett eller flera dokument beroende på projektets behov. Syftet med detta är att tydligt visa vad systemet skall göra för att uppfylla baskraven i visionen. På detta sätt kan din product backlog ses som en detaljering av baskraven, kraven skall vara såpass detaljerade att de går att implementera och testa. Dokumenten arbetas med och uppdateras löpande under projektets gång. Kraven skall vara i prioritetsordning baserat på värde för produkten.

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 Use Cases 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 tekniker som krävs för ert projekt.

Generella krav på krav är:

• Unikt id
• Tydligt förklarande namn
• Typ/klassificering: (enligt någon modell t.ex. Projektkrav, Kvalitetskrav, Funktionellt krav, FURPS+)
• 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
• Icke motsägelsefullt, två krav får inte säga emot varandra.
• Prioritet
• Beroenden till andra krav

Testspecifikationen visar hur testningen ska gå till och hur testning genomförs.

Några angreppssätt för testning är:

• Test cases skrivs med hjälp av kraven. Testar så att systemet har den förväntade funktionaliteten ofta hittar man även svagheter i kraven när denna typ av testfall skrivs.
• Negativ testning – Använder “olämplig indata” och testar förväntade felmeddelanden. Testar det man inte ska kunna göra i systemet även detta ger ofta upphov till förbättrade och nya krav (t.ex. krav för felhantering)
• Automatiserad testning, kod skrivs som testar den kod som finns i systemet automatiskt. Testar att funktionerna i koden fungerar som tänkt. Finns även “robotar” som testar automatiskt via användargränssnittet t.ex. selenium.
• Explorativ testning, testaren använder systemet och loggar vad hen gör, om något oväntat dyker upp kan sedan ett testfall skapas med hjälp av loggen. Kan också ge en lista med förbättringspunkter och inte bara buggar.
• Stresstestning, systemet testas under extrema förhållanden (t.ex. väldigt mycket data, väldigt många användare, väldigt lite minne etc) för att se hur systemet reagerar under dessa omständigheter. Avslöjar ofta problem som kan vara svåra att hitta annars.
• Användartester – slutanvändare får använda systemet för att utföra sina tänkta uppgifter. Problem och kommentarer som uppkommer tas till vara. Kan används för att utvärdera användarvänlighet eller att jämföra olika tillvägagångssätt (A/B – testning). I detta projekt kan användartester göras så enkelt som att låta en eller flera kamrater använda systemet.

Testning i projektet

I detta projekt vill vi att ni strävar efter att sätta upp en testmiljö där ni kan utföra automatiserad testning i form av enhetstestning och integreringstester. Du får själv undersöka vad det finns för verktyg kring testning för just den plattform du jobbar för. Oftast finns det färdiga testramverk som hjälper dig med detta så som mocha för javascript: https://www.youtube.com/watch?v=Q8Jl85FJz4E

Tänk också på att utforma din kod så att den blir testbar. Se till att varje funktion/funktion/modul/metod gör en sak som är enkel att skriva tester till. Naturligtvis är det svårt att testa hela applikationen med dessa automatiska tester eller att man inte kan/klarar sätta upp en automatiserad testningsmiljö för sin plattform. Då kan användartester utformas som man på ett noggrannare sätt måste beskriva i sin dokumentation (se nedan).

Testspecifikationen bör innehålla en testplan där testverktyg och din strategi för hur applikationen testas gås igenom. Kort sagt hur en oberoende testare kan genomföra testerna som hör till applikationen. Vilka tester finns, vilka delar testar de, vilka tester är ev. automatiserade, hur kör man igång dessa tester, vilka tester är manuella, hur går dessa tester till (steg-för-steg), när är de gjorda o.s.v. Vilka delar av applikationen är eventuellt inte testad.

Förutom en testplan ska testspecifikationen innehålla en beskrivning de "test suits" som finns och hur dessa är kopplade till de krav som finns på applikationen samt var i projektet man kan hitta dessa. Varje "test suit" består av flera "test cases" (testfall) för att täcka upp olika möjligheter i koden.

• Test suit - Inloggning till systemet
  • Testfall 1 - inloggning med korrekta uppgifter
  • Testfall 2 - Inloggning med felaktigt användarnamn
  • Testfall 3 - Inloggning med felaktigt lösenord
  • ...

Använder man automatiserad testning med hjälp av testramverk (så som mocha för javascript) dokumenteras testfallen med själva testkoden (ge dem bra beskrivningar som tydligt visar vad testningen går ut på). Gör man användartester ska varje test case dokumenteras i testspecifikationen med följande information:

• Referens till vilket eller vilka krav som testas
• 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 (har man ett användningsfall så har man redan detta.)

Målet är att en oberoende testare skall kunna genomföra och avgöra om 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 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. Ett tecken på att man inte testar bra är att man inte hittar några buggar. Arbeta kontinuerligt med testningen, prioritera testning av riskfyllda delar och vänta inte med testning till slutet! Glöm inte heller att använda din projektgrupp där ni hela tiden kan testa varandras applikationer och på så sätt hitta buggar

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 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.

Projektplanen kan innehålla:

• Projektnamn
• 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å

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.

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 således en viktig input till iterationsplaneringen.

Risklistan bör innehålla:

• Topplista med risker i prioritetsordning
• Riskspecifikationer
  • 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.

Syftet med ordlistan är att föklara termer och begrepp så att missförstånd kan undvikas. Ordlistan kan även tjäna som datadictionary och definiera begrepp i kraven på ett tydligt sätt så att man slipper återupprepa detta hela tiden.