Designdokumentation
Skrivet av Jens Gustavsson - ons, 2006-08-09 14:56
!!Designdokumentation
En beskrivning av de olika rubrikerna nedan finns [här|Generella underhållbarhetskrav].
!Kravtext
Systemet skall levereras tillsammans med dokumentation av dess tekniska design. Dokumentationen skall innehålla:
*En övergripande beskrivning av vilka moduler det består av och hur dessa moduler kommunicerar med varandra.
*UML-klassdiagram med minst 50% av alla klasser i systemet. Sådana klasser som är viktiga för att förstå systemets övergripande design bör finnas med. Diagrammen skall innehålla information om viktiga attribut och operationer hos klasserna, samt relationer mellan dem.
*Entity-relationship-diagram över alla tabeller i databasen.
*En beskrivning av den bärande idén bakom varje klass, interface, typ och tabell i systemet.
*För varje krav i kravspecifikationen, en beskrivning av hur designen uppfyller det kravet.
*Motivering till viktiga designbeslut.
*Use-case diagram med beskrivning för hur respektive use-case implementerats i systemet.
!Förklaring
När man ska göra förändringar i ett system är det värdefullt att ha tillgång till dokumentation som beskriver systemets design.
I princip alla punkterna är svåra att testa. Kostnaden för att skapa användbar dokumentation är dock tillräckligt låg för att inte göra det alltför lockande för leverantören att fuska bort den. Det är svårt att formulera krav på innehåll i dokumentation på något sätt som löser problemet med att de är svårtestade.
För UML-klassdiagram krävs bara att 50% av klasserna dokumenteras eftersom vissa klasser är tämligen ointressanta för att förstå systemets övergripande design och genom att inte kräva att alla klasser finns med i diagrammet uppmuntras leverantören att fokusera dokumentationen på de viktigaste klasserna.
!Kostnad
Inte försumbar, men det är välspenderade pengar.
!Anpassningar
Välj de punkter i kravtexten som är relevanta för systemet och komplettera med ytterligare relevanta punkter.
!Relation till andra krav
Dokumentationen påverkas av eventuella generella dokumentationskrav.
Kommentarer
Jag håller med om att det kan vara trist att skriva och uppdatera dokumentation. Men det är också trist att försöka förstå sig på ett stort system som saknar dokumentation.
Men andra sätt att uppnå de positiva effekterna av dokumentation är spännande. Kan vi på något sätt få nyttan utan kostnaden/arbetet så är det att föredra. De agila utvecklingsmetoderna som t.ex. XP har ju förslag på lösningar, men jag har inte hittat något som klarar att hålla viktig information över lång tid på samma sätt som bra dokumentation. Programkoden, tillsammans med automatiska testfall, byggskript osv. är ju ett förslag, men jag menar att det som tekniken ser ut idag inte är tillräckligt för att den framtida underhållsprogrammeraren ska kunna göra ett effektivt jobb.
Finns det andra bra sätt att slippa slita med manuell dokumentation?
Jens Gustavsson
www.jensgustavsson.se