TDP003 Projekt: Egna datormiljön

Systemdokumentation

Målgrupp

Liksom manualerna har även systemdokumentationen en målgrupp. Denna gång är målgruppen en typisk IP-student i ettan.

Syfte

Anledningen till att vi skriver en systemdokumentation är att underlätta för senare programmerare att snabbt förstå hur systemet är uppbyggt och fungerar. Det är lämpligt att börja med en översiktlig figur av systemet huvudmoduler och hur de samarbetar (arkitektur), och sedan steg för steg gå in på djupare detaljer. På lägsta detaljnivå kan de funktioner som finns i varje delsystem dokumenteras (design).

I dokumentet är det vanligt att visa olika typer av interaktionsdiagram (t.ex. sekvensdiagram) för att redovisa vilka funktioner som anropas och i vilken ordning. Det är även lämpligt att funktioners existens motiveras genom att lista vilka krav som är beroende av funktionen. En modell kan vara att utgå från de funktionella kraven (hänvisa till kravspec) och med ett sekvensdiagram visa vilka funktioner som är involverade och i vilken ordning.

Håll i minnet att målet är att en programmerare som inte vet något om hur portfolion är implementerad skall kunna ändra, rätta eller lägga till funktionalitet utan att behöva läsa all kod. Och det skall bli rätt. En snabb titt i systemdokumentationen skall räcka.

Sekvensdiagram

Ett axplock av exempel på sekvensdiagram:

Krav på systemdokumentationen

Dokumentet är skrivet för att underlätta underhåll av systemets kodbas.
Det skall finnas minst en förklarad översiktsbild.
Det skall finnas hänvisning till kursens specifikation av datalagret.
Funktioner som ingår i presentationslagret skall vara specificerade i detaljnivå motsvarande datalagrets specifikation. Det finns verktyg för att automatiskt generera denna typ av dokumentation utifrån källkoden (till exempel Epydoc). Det förutsätter förstås att källkoden har korrekt formaterade kommentarer.
Det skall finnas minst ett sekvensdiagram för en specifik användarsituation.
Det skall finnas ett avsnitt som beskriver hur fel hanteras och loggas, och var utvecklare kan hitta portfoliologgen (finns exempelvis i terminalen). Här ska även finnas en beskrivning av metoder och program som används vid felsökning, speciellt om koden är förberedd för ett specifikt verktyg eller en specifik metod. Under utveckling skapas ofta enhetstester, dokumentera vilka som finns och hur de används (exempelvis de gemensamma testfallen).

Riktlinjer för systemdokumentationen

Bilder/figurer ska ha förklarande figurtexter med nummer, och de ska refereras till i texten.
Det skall finnas information om författare, datum, dokumentversion, projektnamn, kurs och totalt antal sidor (dessa saker är bra att ha med i en dokumentmall, t.ex. i sidhuvud/sidfot på varje sida).
Inlämning sker som pdf med höga krav på språk och tydlig layout. Korrekturläs. Använd flera rubriknivåer. Sätt tydliga relevanta rubriker. Använd bilder och figurer för att förtydliga eller exemplifiera det som beskrivs i text. Numrera figurer och tabeller och hänvisa i texten så bilden ingår i den röda tråden. Formatera konsekvent kod, filnamn, eller andra typer av nyckelord med en annan font. Infoga innehållsförteckning om det är motiverat utifrån sidantalet, färre än fem sidor behöver sällan förteckning, det är lätt hitta ändå.

Sidansvarig: Pontus Haglund
Senast uppdaterad: 2023-08-28