Om dokumentasjon
I et prosjekt er det alltid et spørsmål om hvor mye vi skal dokumentere og hva vi skal dokumentere. Vi skal forsøk å gi noen retningslinjer for dette, selv om det er du selv som må finne svaret.
Hvorfor dokumenterer vi?
Det er i alle fall helt sikkert, vi dokumenterer ikke for å få flest mulige vakre dokumenter. Vi lager dokumentasjon fordi den skal brukes til noe. Fordi dokumentasjonen er nødvendig, vi kan ikke klare oss uten.
Trosretninger når det gjelder dokumentasjon
Når det er sagt, så finnes det mange ulike trosretninger for hva som er nødvendig dokumentasjon. I den ene ekstreme enden av spekteret finner vi dem som mener at vi nærmest ikke trenger noe, i den andre enden finne vi dem som sverger til det vi kaller en dokumentdrevet prosess. Populært sagt er dette en prosess hvor det å "få ferdig" dokumentene lett blir det som driver oss frem, og er tegn på om vi har gjort det vi skulle. Med andre ord - dokumentene blir lett et mål i seg selv. Vi befinner oss et sted i mellom disse ytterpunktene.
Kriterier for å bestemme hva som skal dokumenteres
Etter vårt syn er det noen grunnleggende spørsmål som kan hjelpe deg til å velge hva du skal dokumentere.
Vi mener du skal dokumentere noe hvis, og bare hvis det du dokumenterer er nødvendig:
som grunnlag for å forstå og sjekke ut forståelsen (f.eks hos bruker)
som grunnlag for videre arbeid (her holder ikke argumentet om at informasjonen finnes i hodet hos noen)
som grunnlag for å få tatt en beslutning
fordi det skal leveres til oppdragsgiver som en del av sluttproduktet
Du må også stille deg spørsmålet om hva som skjer hvis du ikke dokumenterer en sak:
Hva koster det å utvikle (og vedlikeholde) dokumentasjon sammenlignet med hva det koster hvis vi ikke har dokumentasjon (for eksempel hvis noen blir syke, eller slutter, eller vi blir uenige om hva vi egenlig var enige om)
Kan deler av dokumentasjonen genereres automatisk av de verktøyene vi bruker?
Kan deler av dokumentasjonen erstattes av en kjørbar systembit (prototyp)?
Er du i tvil må du huske på at det er bedre å dokumentere litt for mye enn litt for lite!
Og husk: når du først bruker ressurser på å dokumentere, så legg vekt på å lage god dokumentasjon!
Legg vekt på at innholdet skal gi en tilstrekkelig beskrivelse av det som dokumenteres
Legg vekt på at all viktig informasjon er lett å ”få øye på” for en ny leser.
Skriv så kort som mulig
Skriv så presis som mulig
Legg vekt på godt språk
Legg vekt på en ryddig organisering av dokumentet, med forside, innledning, innholdsfortegnelse, sidenummerering etc.
Revisjon av dokumentasjon
Det kan alltid bli behov for å endre deler av dokumentasjonen senere i prosjektet. Vi har i prinsippet to måter å gjøre det på:
Vi kan lage en revidert utgave av dokumentet Pass på å merke dokumentet slik at det går tydelig frem at dette er en revidert utgave. Ta med dato for revisjonen. Det er vanlig innledningsvis å ta med en kort oppsummering av hvilke endringer som er gjort.
Vi kan inkludere de delene av dokumentet som må revideres i senere dokumenter under overskriften: Revisjon av xxxxx
Hvilken fremgangsmåte vi velger er avhengig av hvor omfattende revisjonene er. Ved større revisjoner er det naturlig å lage en revidert utgave av dokumentet, mens ved mindre justeringer er det naturlig å ta endringene inn i egne kapitler i senere rapporter.
Ansvarlig for dokumentet: Greta Hjertø