Systemdokumentation

Att skriva bra teknisk dokumentation verkar, av vad man sett, att vara svårt (men borde det vara det?). Alltså är nog detta en utmaning!

Mitt förslag:

OBS! Checklista med förslag, allt kanske inte behöver tas medi dokumentation. Det kan också fattas någon aspekt som kan vara viktigt för ditt projekt! Som alltid - var kritisk!

Krav och ambition på systemdokumentation
- Vad är syftet och mål?
  - Syfte: Vad skall det gå att göra med hjälp av dokumentationen? (Document Purpose!)
  - Mål: Vad skall då finnas i dokumentation, hur skall det presenteras och hur skall det läsas?
- För vem skriver du? (Dokumentets aktör)
- Vad skall läsaren få ut? Vad vill hen kunna göra m h a dokumentationen?
- Formalitet (detaljnivå, versionshantering, lagringsplats, spårbarhet, sekretess, rättigheter, uppdatering mm)
- Samla information i ämnet (teknisk IT-dokumentation). Hitta bra exempel som liknar ditt behov. Hitta bra mallar att utgå ifrån (wiki, dokument, ..)
Vilka principer skall du använd i din dokumentation?

Vilken pedagogik, didaktik och metod skall användas? I vilken mentala och fysiska situation befinner sig läsaren och vad är då bra teknisk dokumentation (pedagogik)?
Wiki, dokument, blandning eller annan typ?
Från helhet till detaljer eller från detaljer till helhet?
"Black box" och "White box"?
"En bild säger mer än tusen ord" men behöver ofta förklaras med text.
Modeller och abstraktioner (viktigt och mycket användbart - ingenjörskonst - måste finnas med)
- Modelleringsstandard (UML, strukturdiagram, konceptkartor, mindmaps ..)
Statisk och dynamisk beskrivning? Tillståndsbeskrivningar?
mer?

Vilka delar skall ingå? Vilka områden skall täckas?

Kravspec på delmodul (funktionella- och ickefunktionell, (prestanda, säkerhet, ...)
In- och utparametrar
Arkitektur, design, implementation, drift, avveckling - ritningar och specifikationer
Kända brister och fel, förslag på förbättringar
Testspecifikationer
Övrigt
- Miljö- och hållbarhetsaspekter (sophantering, återvinning, miljöbelastning, användning, ..)
- Etik/moral ("fare-trade", demokrati, valbarhet ...)
- JML
- Arbetsmiljö

Sammanfatta ovan och gör en dokumentations-"designlösning" - en struktur

Wiki-träd? Dokument? Blandning?
Dokumentstruktur (dokumentdesign) - Innehållsförteckning (Titel, kapitel, underkapitel, bilagor, korsreferenser, referenser)

Testa designlösningen för dokumentation och dokument genom att fundera på om den löser uppsatt syfte, användning och behov. Testa på någon person som motsvara en angiven aktör! Kan hen utföra det som avses m h a av din tekniska dokumentation?
Finns det en "röd tråd"? Får läsaren information i rätt ordning? Kan läsaren hitta och "navigera" fram och tillbaka i informationen?
Är innehållet "lagom" ( d v s K.I.S.S) för ändamålet?
Börja konstruera/skriv innehåll i dokumentet.
Pröva och ifrågasätt dokumentationen och dokumentets "designlösningen" kontinuerligt - ändra och förbättra! Uppfylls syfte och mål?
"Teknisk skuld"? Vilken teknisk skuld lämnar du efter dig i din komponent?

Mall för teknisk dokumentation

Som utvecklare så skapar man "komponenter". Från "Essence Kernel" kan man hämta Word-mallen "essup_component_description_template.dot" som kan vara en bra utgångspunkt för systemdokumentation.

Essence Card "Component Description" finns här (länk) som är en del av Essence (länk) eller på "Practice Library", Alpha-component, Component description, Component practice

Hela slutrapporten med bilagor

Som en bilaga i gruppens slutrapport så skall du bifoga din tekniska dokumentation för någon systemkomponent som du utvecklat i projektet.

Hela rapporetn som "UC-model"