Instruktioner för systemdokumentation
Här beskrivs systemet ur systemteknisk synvinkel. Dokumentet är riktat till den eller de personer som har underhållsansvar och utgår ifrån att läsaren har adb-utbildning bakom sig. Systemdokumentationen beskriver systemet mer ingående både ur logisk och fysisk synvinkel och tanken är att det här skall stå allt vad man behöver känna till för sköta systemunderhåll och vid behov förbättra eller bygga ut systemet.
Pärmsida, sidhuvud och -fot
Det som står i de allmänna instruktionerna om pärmsida och sidhuvud och -fot gäller även för systemdokumentationen. Se här.
1 Inledning
1.1 Syfte och...
Ger en översikt över program-varan och dess betydelse för verksamheten och föver den tekniska plattformen som systemet vilar på.
1.2 Programvara och ...
Programvarans namn, syfte och hur den används i verksamheten. Beskrivning av användare och användningsområde.
1.3 Definitioner...
Ord, uttryck och termer som är okända för läsaren (beställare / leverantör) och som har väsentlig betydelse. En förteckning i bokstavsordning.
2.1 ...användningsområde
Beskrivning av en större omgivning dit programvaran / systemet hör. Användnings-området är den del av verksamheten som berörs, internt och externt i företaget.
2.2...kopplingar...
Hur ser omgivningen ut. Är systemet en del av ett större system? Finns det kopplingar (bryggor) till andra system, d.v.s skickas eller tas data emot från andra system.
2.3 Teknisk plattform
Beskrivning av den tekniska plattformen, t.ex.dator och kringutrustning, kapacitets-behov, operativsystem, nätverksspecifikationer, datakommunikation med andra datorer, begränsningar m.m.
2.4 Programvara
Den programomgivning som systemet finns i, t.ex. operativsystem, program-translator, hjälpprogram, databasprogram (engine), datakommunikationsprogram, protokoll, www-läsare, kopplingar till andra program, andra programvaror som körs på samma gång, utnyttjande av gemensamma moduler eller program, standarder, m.m.
Kom ihåg att ange versionsnummer.
5 Övriga speciella...
Här tas upp vid behov t.ex.
- datasäkerhet, behörighet
- säkerhetskopiering
- restore-rutiner
- underhållsrutiner
- flexibilitet
- portabilitet
- kompabilitet
Innehåll
3 Systemarkitektur
Här beskrivs programvarans systemarkitektur i allmänna termer i syfte att ge läsaren en översikt.
3.1 Databasarkitektur
Beskrivning av databasstrukturen, såsom uppdelning i datalager (databaser tabeller och/eller register), beroendeförhållande mellan olika datalager, organisation av datalager, eventuella databasgeneratorer (databas engines), behörighetssystem, backup- och restorerutiner och -program, löpande underhållbehov.
Beskrivning av databasen och dess struktur, t.ex. tabeller, nyckelfält och realtionsfält samt relationer mellan tabeller ifall det är fråga om en relationsdatabas.
Databasen beskrivs detaljerat:
- Allmän beskrivning
- Vilka andra program behöver/använder databasen
- Hur tas säkerhetskopior och hur sker återställning av databasenvis eventeullt databashaveri - vilka hjälpprogram (utilityprogram) behövs
- Strukturer, relationer, logiska kopplingar
- Databasen
- Allmän beskrivning av databasinnehåll
- Databastyp (Access, Dbase, Oracle...)
- Relationer till andra databaser/tabeller/register
- Uppdateringskriterier och -sätt
- Utrymmesbehov (Skivutrymme i MegaByte alt. GigaByte)
- Underhållsbehov
- Säkerhetskopieringsbehov
- Datasäkerhetsaspekter, Databehörighet
Databasen alla fält beskrivs detaljerat:
- Entydig namn och en kort förklaring till informationsinnehållet
- primärnyckel, sekundärnyckel, relationsfält
- Typ och längd
- Valideringskontroll och eventellt defaultvärde
- Behandlingsregler för data/information
- Relationer till andra fält (annan data/information)
3.2 Programarkitektur, moduler, processer
Detta kapitel är ett viktigt planeringsdokument. Det är viktigt att i ett tidigt skede bestämma nivån på beskrivningen. Utgångspunkten är att läsaren har en djupare adb-kunskap än en slutanvändare, men läsaren är nödvändigtvis inte en "fullfjädrad" programmerare och texten skall skrivas med tanke på läsaren.
Om denna text blir alltför detaljerad är risken att den inte kommer att underhållas i takt med programändringar (leder till att innehållet blir inaktuellt/felaktigt efter en tid) och det kan ibland vara bättre att hänvisa till programkoden för att reda ut detaljer. En alltför generell beskrivning är dock inte heller till någon nytta för läsaren. Detta dokument skall ge en djupare kunskap än den som finns i användardokumentet och skall fungera som en "nyckel" som ger hänvisningar till var man kan gå ännu djupare in i programmens/systemets lösningar.
Saker som kan tas upp i detta kapitel:
- Programuppdelning i system / delsystem / program/ moduler / processer / klasser
- I objektorienterade system används termer som: objekt / klasser (class) / komponenter (component) / paket (package)
- Logiska programbeskrivningar med någon beskrivningsteknik, t.ex.
- Flödesschema
- Pseudokod
- Nassi-Schneiderman Diagram
- Ifall det är fråga om objektorienterade system används andra beskrivningstekniker som baseras på någon standard, t.ex. UML (Unified Modelling Language). Exempel på diagram enligt UML:
- AnvändningsfallsDiagram (UseCase Diagram)
- InteraktionsDiagram (SequenceDiagram)
- SamarbetsDiagram (CollobartionDiagram)
- KlassDiagram (Class Diagram)
- TillståndsDiagram (StateDiagram)
- AktivitetsDiagram (ActivityDiagram)
4 Moduler (program och processer)
Här beskrivs uppdelningen i moduler, program och processer och hur dessa fungerar ihop och bildar en logisk systemhelhet. Det är önskvärt att inleda med en översikt (t.ex. flödesschema), som beskriver helheten för att sedan i den fortsatta texten beskriva varje del mer detaljerat (=analyserande synsätt).
Denna översikt ger helehtsbilden och fungerar på samma gång som en källa där man snabbt kan se vilken logsik uppdelning som systemet består av och hur modulindelningen gjorts och vilka program som "buntats ihop" till logiska helheter.
Kommenater: Modularisering innebär att "bunta ihop" program i lämliga logiskt sammanhängande helheter som tillsammans bildar moduler (synonymer kunde vara: komponenter, paket).
Modulariseringen har stor betydelse för den slutgiltiga kvaliteten på programvaran och beslutet bör tas i ett tidigt skede (analysskedet) av planeringsprocessen och det inverkar i hög grad på olika kvalitetsfaktorer som funktionalitet, portabilitet, kompabilitet.
Hierarkiskt indelas systemet i olika moduler som består av program som i sin tur utför olika processer beroende på interaktionen med användaren (eller med andra system). Modulerna kan använda gemensamma program (t.ex. underprogram för kontroll av socialskyddssignum) eller göra anrop till varandra via programkoden. Syftet med att modularisera är att skapa helheter med hög samhörighet inom den egna modulen och låg koppling till "främmande" moduler. (Samma gäller inom objektorienterade system där man istället för moduler pratar om komponenter) .
Modulerna och programmen beskrivs sedan en efter en i egna kapitel.
4.1 Modul X
Varje modul beskrivs i eget kapitel. Det är bra att komma överens om gemensamma beskrivningsregler (programmeringsstandarder), t.ex. namnstandarder för program, procedurer, variabler och funktioner, språk (svenska engelska?), användning av stor bokstav (t.ex. UppdateraKund), användning av underline (t.ex. beräkna_kundrabatt_per_år).
4.1.1 Allmän beskrivning
För varje del som ingår i modulen beskrivs:
- Standardenligt modulnamn (som det igenkänns i systemet)
- Typ av program
- Program, underprogram, funktioner
- När det gäller objektorienterade system heter det: paket, komponenter, klasser, objekt, operationer, processer
- Allmän beskrivning av vad modulen uträttar i systemet
4.1.2 Replikplanering
För varje program där det sker en interaktion mellan användare och dator görs en replikplanering, som beskriver vilka element och knappar användaren har till förfogande för att uträtta de funktioner systemet är byggt för. I planeringsskedet är det ett dokument som beskriver för programmeraren vad som skall göras och i implementeringen ett underlag för testning av program.
4.1.3 Program
Beskrivning av sättet på hur modulen/programmen skall utföra önskade funktioner med hjälp av de bearbetnings- och behandlingsregler som definierats för informationen i databaserna. Programlogiken, åtminstone huvudflödet i viktiga program beskrivs med hjälp av t.ex. pseudokod, flödesscheman eller Nassi-Schneiderman diagram.
Dessa ligger till underlag för programmeringen och testningen. Här gäller det att efter implementeringen av systemet avgöra hur mycket av detaljerna som skall finnas kvar då denna dokumentation överlåts till underhållsorganisationen och göra en avstämning mot de program som skapats. En god programmerare ser till att dokumentera viktiga funktioner även direkt i programmet.
4.1.4 Felrutiner
Beskrivning av hur modulen/programmen är programmerad för olika typer av felsituationer. Språket i olika felmeddelanden skall anpassas till användarkategorin och det kan finnas vissa felmeddelande som är tänkta för användaren och andra som är tänkta för underhålls-organisationen. Skilj på dessa!
Om det i testningsskedet har upptäckts fel eller brister, som ännu inte är åtgärdade bör de nämnas här. Det kan finnas beslut i projektet att dessa åtgärdas senare, eftersom de inte är kritiska för ibrukstagningen.
Åtminstone följande utreds och dokumenteras::
- Vilka felsituationer har beaktats i programmen
- Hur behandlas en viss feltyp
- Hur meddelas användaren om detta fel
- Vilka åtgärder krävs för att komma ur felet
- Finns det en inbyggd felloggning
Det gäller att förenhetliga felrutiner och felmeddelanden. Detta inverkar i hög grad på användarvänligheten och på hur användaren uppfattar systemets stabilitet.
Tänk på att:
- Förenhetliga regler för felmeddelanden
- Göra om möjligt en egen modul för felbehandlingen, som kan användas av olika program
- överväg att koda/klassificera felmeddelanden - det kan finnas olika grad av allvarlighet i felsituationer, som skall åtgärdas på olika sätt
- Avgöra om felen skall loggas och om de bör sparas för senare analys
- Formulera felmeddelanden som kan förstås av den som det är ämnat för (användare?/adb-personal?/programmerare?)
