Sjekkliste for dokumentasjonskvalitet
Et praktisk grunnlag for å vurdere om dokumentasjon er komplett, forståelig og etterprøvbar.
Sjekklisten kan brukes ved gjennomgang av dokumentasjon for datastrukturer, felter, kodeverk, grensesnitt og valideringsregler. Den vurderer ikke om en bestemt løsning følger lov eller en autoritativ standard.
Bruk kolonnene ja, delvis, nei og ikke relevant, og skriv en kort begrunnelse for alle svar som ikke er «ja».
1. Formål og målgruppe
- Er formålet med dokumentasjonen uttrykt i én tydelig setning?
- Er det forklart hvilke oppgaver dokumentasjonen skal støtte?
- Er primære lesere identifisert?
- Er nødvendig forkunnskap oppgitt?
- Er forholdet til andre dokumenter og regler forklart?
2. Omfang og avgrensning
- Er det tydelig hvilke data, prosesser og perioder dokumentasjonen gjelder?
- Er det beskrevet hva som faller utenfor?
- Er obligatoriske, valgfrie og betingede deler skilt fra hverandre?
- Er geografiske eller organisatoriske avgrensninger angitt?
- Er forutsetninger og avhengigheter synlige?
3. Begreper
- Har sentrale begreper entydige definisjoner?
- Er nærliggende begreper skilt fra hverandre?
- Brukes samme begrep konsekvent gjennom hele dokumentet?
- Er forkortelser skrevet fullt ut første gang?
- Er den autoritative kilden oppgitt når definisjonen kommer fra andre?
4. Dataelementer
For hvert dataelement bør dokumentasjonen angi:
| Egenskap | Kontrollspørsmål |
|---|---|
| Navn | Er både teknisk navn og lesbart navn oppgitt? |
| Betydning | Er det forklart hva verdien representerer? |
| Type | Er datatype, format og eventuell enhet angitt? |
| Forekomst | Er minimum og maksimum antall forekomster oppgitt? |
| Betingelse | Er regelen for når elementet skal finnes, uttrykt presist? |
| Kodeverk | Er navn, kilde og versjon identifisert? |
| Tom verdi | Er forskjellen mellom manglende, tom og null forklart? |
| Eksempel | Finnes både et normalt og et vanskelig eksempel? |
5. Regler og validering
- Kan hver regel spores til et uttrykt krav?
- Er alvorlighetsgrad eller konsekvens ved regelbrudd forklart?
- Er betingelser skrevet slik at de kan testes?
- Er avrunding, toleranser og fortegn dokumentert?
- Er regler som går på tvers av flere dataelementer identifisert?
- Er forventet håndtering av ukjente koder eller fremtidige verdier beskrevet?
- Finnes eksempler som både skal bestå og feile?
6. Eksempler og testgrunnlag
- Representerer eksemplene realistiske situasjoner?
- Er personopplysninger og fortrolig informasjon fjernet?
- Er vanskelige grenseverdier tatt med?
- Er forventet resultat forklart?
- Kan eksemplene gjentas uten skjulte forutsetninger?
7. Versjonering og endringer
- Har dokumentet et synlig versjonsnummer eller en entydig utgave?
- Er publiserings- og gjennomgangsdato oppgitt?
- Er det tydelig hvem som forvalter dokumentet?
- Finnes en endringsoversikt for vesentlige endringer?
- Er bakoverkompatibilitet eller overgangsperiode forklart?
- Er utgåtte deler tydelig merket?
8. Tilgjengelighet og brukbarhet
- Kan dokumentet leses uten tilgang til lukkede arbeidsverktøy?
- Har overskrifter og tabeller en logisk struktur?
- Fungerer alle lenker?
- Er språk og eksempler tilpasset målgruppen?
- Kan en ny leser finne definisjoner, regler og endringer raskt?
Oppsummering
Et dokument bør ikke vurderes som klart bare fordi alle overskrifter finnes. Gjennomgangen må også spørre om en uavhengig leser kan:
- forstå formålet
- identifisere hva som kreves
- skille krav fra forklaring
- prøve reglene på et eksempel
- finne kilde og versjon
- oppdage hva som er endret
Funn som ikke kan løses med en enkel rettelse, kan beskrives med malen for faglige problemnotater .