Dokumentasjonsguide for
Systemutvikling i
SAUS
UTKAST
Innhold
- Hvorfor dokumentere?
- Typer dokumentasjon
- Krav til dokumentasjon
- Dokumentasjonsguider for de enkelte områdene
- Hvordan finne dokumentasjonen?
- Hvor lagres dokumentene?
- Vedvarende forbedring
Ved de årlige seminarene i seksjon SAUS har vi bl.a. diskuterte hva seksjonen legger i begrepet kvalitet, og hvordan vi skal oppnå en forbedret kvalitet. Et av de viktigste punktene som kom fram, var at seksjonen måtte forbedre dokumenteringen sin, og vi satte oss som mål å bli den beste seksjonen på dokumenterering. Målet er at denne web-siden skal inneholde retningslinjer og tips for å gjøre dokumentering enklere og mer samkjørt/strukturert. Siden inneholder også lenker til web-sider som inneholder lister med dokumentasjon seksjonen har tilgjengelig. Disse kan brukes som eksempler, og utgangspunkt for utforming av ny dokumentasjon.
Alle nye systemer som skal utvikles i vår seksjon skal dokumenteres etter retningslinjene under, og ingen prosjekter er ferdigstilt før dokumentasjonen er på plass. Dokumentasjon skal inn i alle prosjektplaner, slik at det blir satt av tilstrekkelig tid til dette fra starten.
Det er laget en pdf-versjon av dette dokumentet som er egnet for utskrift på papir.
1. Hvorfor dokumentere?
Dokumentasjon er viktig i alle ledd. Under har vi satt opp en liste over de viktigste grunnene til å dokumentere:
- Gjøre vedlikehold og videreutvikling mindre personavhengig.
- Gjøre oss mindre sårbare når folk er syke, slutter o.a.
- Gjøre det mulig å overføre til drift fra utvikling.
- Gjøre det enklere for brukere å lete fram tjenester/systemer.
- Redusere behovet for brukerstøtte, samt gjøre det enklere for brukere.
- Gjøre det enklere å koble forskjellige systemer.
2. Typer dokumentasjon
Vi har valgt å dele dokumentasjonen opp i fire kategorier, hvor kategoriene dekker hvert sitt område. For hver av de ulike kategoriene, har vi definert tips og retningslinjer for hvordan dokumentasjonen bør skrives, hvor den skal ligge m.m. De ulike kategoriene er som følger:
2.1 Presentasjon av
systemet er dokumentasjon som er retta mot alle som trenger en
systemoversikt. Dokumentasjonen skal beskrive systemets overordnete struktur og
gi modeller som ligger til grunn for systemet. Kravspesifikasjon for systemet,
og eventuell behovsanalyse, er også aktuelle her. Det samme gjelder annen
overordnet dokumentasjon fra systemets utviklingsfase. Systempresentasjon er
beregnet på systemeier, superbrukere, systemutviklere etc., og skal gi
disse et overordnet bilde av systemet. Systempresentasjon omfatter minst tre
typer dokumenter:
1. Overordnet
systemmodell
2.
Markedsføringsmateriell
3.
Kravspesifikasjon for systemet
Til denne kategorien dokumenter hører
også det som eventuelt fins av dokumentert behovsanslyse for
systemet.
2.2 Brukerdokumentasjon består gjerne av en eller flere brukermanualer, samt en generell beskrivelse av hva systemet er og hvem det kan være aktuelt for. Dokumentasjonen skal være dekkende både med tanke på eksisterende og potensielle brukere.
2.3 Driftsdokumentasjon koordineres med Houston/Houdini og skal beskrive alt som omhandler drift av systemet. Momenter i denne beskrivelsen er hvordan systemet startes/stoppes, hva systemet er avhengig av, hva som er avhengig av at dette systemet fungerer, sjekkliste ved systemheng, kontaktpunkt til utvikler/systemeier osv.
2.4
Utviklerdokumentasjon er rettet mot feilsøking, vedlikehold og
videreutvikling av systemet. Dokumentasjonen skal beskrive strukturen i
systemet, modeller som ligger til grunn, og ikke minst gi dokumentasjon av
kildekoden. Dette omfatter også testdokumentasjon og eventuell
API-dokumentasjon. Utviklerdokumentasjon vil være sterkt preget av de
metoder og verktøy som brukes i utviklingsarbeidet. På dette punkt
må derfor store deler av innholdet i denne guiden bare betraktes som et
begrenset eksempel på hvordan ting kan dokumenteres. Og i hvert enkelt
prosjekt må utviklerdokumentasjonen tilpasses de metoder og
verktøy som brukes i systemutviklingen. Utviklerdokumentasjon omfatter
minst fire ulike typer dokumenter:
1.
Designdokumentasjon
2. Dokumentasjon i
kildekoden
3. Testdokumentasjon
4. API-dokumentasjon
Begrepet systemdokumentasjon brukes som en samlebetegnelse på alle de dokumentene som er nevnt her. For en del systemer, vil selvfølgelig enkelte av de ovenstående kategoriene være overflødige. Eksempelvis vil brukerdokumentasjon kunne være meningsløs for en applikasjon/komponent som brukere aldri vil benytte direkte. Men for de fleste applikasjoner, er det viktig at man har dokumentasjon som fyller behovene i alle aktuelle kategoriene.
For systemer som er utviklet ved USIT vil vi vanligvis ha en samling av historisk prosjektdokumentasjon fra den tid systemet ble utviklet. Dette kan betraktes som en del av systemdokumentasjonen både fordi det kan være av interesse i forbindelse med videreutvikling og drift av systemet, og fordi det kan inneholde informasjon om viktige erfaringer for senere prosjekter.
Konvensjoner ved utvikling. I tillegg til dokumentasjonen for hvert enketl system/prosjekt skal seksjonen ha felles dokumentasjon av konvensjoner for systemutvikling/vedlikehold. Dette skal bidra til å sørge for at seksjonen benytter relativt like konvensjoner når man utvikler applikasjoner. Dette er viktig med tanke på at det skal være enkelt for andre å overta utvikling av et system. Eksempel på konvensjon kan være hvordan vi ønsker fil- og prosjektstruktur o.l. ved utvikling av servletsbaserte webapplikasjoner. I tillegg kan denne kategorien suppleres med forslag til lure "pattern", "hacks" og "tankemåter" man har tilegnet seg med erfaring ved utvikling. Alle systemutviklingsprosjekter skal vurdere å bidra til videreutvikling av dokumentasjonen for disse konvensjonene.
3. Krav til dokumentasjon
Det har vært diskutert ganske mye om hvor mye man skal kreve av dokumentasjon og hvor mye føringer som skal legges i forbindelse med utvikling av maler, bestemmelser om bruk av verktøy osv. Men vi har funnet ut at det viktigste er at sluttresultatet er ganske likt og at man samler dokumentasjonen under portaler slik at det blir enkelt å finne fram.
Egnete verktøy og maler vil variere sterkt avhengig av hvilke språk/verktøy et produkt er utviklet i, samt hva som er viktig å dokumentere for et gitt system. Likevel har vi nedenfor satt inn retningslinjer og enkelte maler man kan benytte slik at man slipper å utvikle dette selv først. Hvis man har forslag til nye maler som bør legges inn, er vi glad for slike tilbakemeldinger.
En annen viktig ting er å kontrollere at dokumentasjon holder mål. Her er det vanskelig å bruke verktøy eller å sette opp regler for når dokumentasjonen er god nok. Det viktigste rådet er å la andre lese gjennom dokumentasjonen som er skrevet. Vi anmoder derfor sterkt om at alle dokumentasjon skal prøves ut på reelle mottakere før den ferdigstilles.
4. Dokumentasjonsguider for de enkelte områdene
I avsnittene under vi har lagt inn dokumenter med rettledninger og tips i forbindelse med skriving av dokumentasjon i de forskjellige kategoriene. Noen eksempler er også registrert inn for hver kategori.
4.1 Systempresentasjon
- Guide og tips for skriving av systempresentasjon:
- Overordnet systemmodell
- Markedsføringsmateriell
- Kravspesifikasjon for systemet - Web-side med eksempler på systempresentasjon
4.2 Brukerdokumentasjon
4.3 Driftsdokumentasjon
4.4 Utviklerdokumentasjon
- Guide og tips for skriving av utviklerdokumentasjon:
- Designdokumentasjon
- Dokumentasjon i kildekoden
- Testdokumentasjon, se Testguide for SAUS
- API-dokumentasjon - Web-side med eksempler på utviklerdokumentasjon
5. Hvordan finne dokumentasjonen?
Hovedfokus for denne dokumentasjonsguiden er produksjon av dokumentasjon. Men i dette avsnittet tar vi med litt om hvordan man finner fram til eksisterende dokumentasjon for tjenester som USIT leverer og systemutvikling som pågår ved USIT.
5.1 For pågående prosjekter
Alle pågående prosjekter skal ha sin egen nettside, og det er den beste kilden for informasjon om den dokumentasjon prosjektet har produsert eller er i ferd med å produsere. Se listene over nettsidene til interne prosjekter og eksterne prosjekter ved USIT. En del prosjekter som er avsluttet er også med i disse listene, mens enkelte prosjekter som er under etablering muligens mangler.
5.2 For tjenester som er i drift
Alle tjenester som USIT leverer, og dermed alle datasystemer som USIT har ansvar for, skal på sikt være registrert i Houdini. I Houdini registreres URLer til både driftsdokumentasjon, brukerdokumentasjon, utviklerdokumentasjon og annen dokumentasjon for tjenesten. Dermed blir Houdini den viktigste sentraliserte kilde for all informasjon om eksisterende dokumentasjon for alle tjenestene til USIT. Se for eksempel det som er registrert om timeføringssystemet i Houdini, med bl.a. URLer til driftsdokumentasjonen og brukerdokumentasjonen for timesystemet.
Registrering av tjenester i Houdini pågår. Men det vil antakelig gå ut i siste del av 2004 før alle de viktigste tjenestene til USIT er registrert i Houdini. Til da må man om nødvendig bruke andre kilder for å finne dokumentasjonen for en gitt tjeneste. For eksempel:
- For flere av tjenestene til USIT kan man finne dokumentasjon ved å gå til internsidene til den aktuelle tjenestegruppen under: http://intra.usit.uio.no/tj-grupper/index.html
- Dokumentasjon om drift av webtjenester er samlet på ett sted, og tilsvarende med dokumentasjon for utvikling av webtjenester
6. Hvor lagres dokumentene?
SAUS (eller USIT) har ikke noe sentralt arkiv der systemdokumentasjon lagres, men vi har en del forskjellige etablert sedvaner for valg av lagringssted. Det kan tenkes at man på sikt vil endre dette, men argumentasjonen i den saken skal vi ikke ta opp her. Med elektronisk lagring av dokumenter har man den fordel at man kan ha både felles og skreddersydde opplegg for gjenfinning av dokumentene, selv om man ikke har noe felles opplegg for lagring av dokumentene. Men det et noen hovedregler som må følges:
- Pekere til dokumentene må legges der brukerne av dokumentene forventer å finne disse, f.eks. på prosjektsider og websider for tjenestene. På sikt vil de som jobber med drift forvente at pekere til all relevant dokumentasjon ligger i Houdini.
- Dokumentene må lagres på et sted der de og bare de som skal ha tilgang til dokumentene får tilgang. Det kan bety at man velger lagringssted ut fra hensyn til hvem som har adgang til lagringsstedet, eller at man velger et lagringssted som har et egnet opplegg for tilgangskontroll.
- Dokumentene må lagres et sted der de er siktet mot å gå tapt.
7. Vedvarende forbedring
Dette dokumentet er et første ledd i å forbedre dokumenteringen vår. Det er et mål at våre dokumentasjonsrutiner skal bli bedre med tiden, og i dette arbeidet er det viktig at denne dokumentasjonsguiden blir vedlikeholdt og oppdatert. Vi er derfor glad for tilbakemeldinger om ting som kan forandres, legges til osv.
Enhet: USIT, webredaksjon@usit.uio.no
Forfatter: Håvard Fosseng, Torstein Skard og Terje Bakka
Dokument opprettet: 24.05.2002, endret: 08.02.2005Administrer dette dokumentet