Dokumentation

Nedan följer en genomgång av de dokument som du 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.

GitLab Wiki

Dokumentationen skall uteslutande presenteras via dit projekts Wiki-sidor. Ett exempel på struktur tillsammans med beskrivande texter hittar du redan genererat i ditt projekts Wiki.

Vill du veta mer om hur du arbetar med Gitlab-wikis så kan du läsa om det här: Gitlab Docs/Projects/Wiki

Observera att Wikin i sig är ett eget repo så att du kan enkelt klona 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: Du 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 du 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 du 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.