Dokumentasjon er en del av standarden
En standard uten god dokumentasjon blir lett til lokal tolkning. Derfor må dokumentasjon behandles som en del av standardarbeidet, ikke som et tillegg.
En standard kan være godt ment og teknisk korrekt, men fortsatt fungere dårlig i praksis hvis dokumentasjonen er svak. Dokumentasjon er en del av standarden, fordi det er gjennom dokumentasjonen brukerne skjønner hvordan strukturen faktisk skal brukes.
Hvorfor dokumentasjon ikke kan komme til slutt
Hvis dokumentasjon behandles som et tillegg etter at standarden er bestemt, oppstår ofte de samme problemene:
- brukere tolker krav ulikt
- implementasjoner glir fra hverandre
- feilretting blir tidkrevende
- standarden oppleves mer uklar enn den egentlig trenger å være
Dette gjelder både for kontoplaner, eksportformater og e-faktura.
Hva god dokumentasjon bør inneholde
| Innhold | Hvorfor det er viktig |
|---|---|
| Begrepsforklaringer | Reduserer misforståelser mellom fag og system |
| Eksempler | Viser hvordan standarden er ment å brukes i praksis |
| Feilscenarier | Hjelper brukerne å forstå vanlige avvik |
| Mapping-prinsipper | Gjør implementasjon mer lik på tvers av løsninger |
| Endringsbeskrivelse | Gjør videreutvikling mer forutsigbar |
Dokumentasjon er særlig viktig når standarden blir mer detaljert
Jo mer detaljert en standard er, desto mer trenger brukerne forklaringer. Det gjelder blant annet for:
Hvis detaljeringen øker uten at dokumentasjonen følger med, blir resultatet ofte mer usikkerhet i stedet for bedre standardisering.
God dokumentasjon gjør standarden lettere å vedlikeholde
Dokumentasjon er ikke bare viktig for førstegangsbruk. Den gjør det også lettere å:
- forklare hvorfor en løsning er valgt
- diskutere forbedringer på et mer presist grunnlag
- innføre nye versjoner uten å skape unødvendig brudd
- få innspill fra flere enn dem som allerede kjenner standarden godt
Det siste er særlig viktig hvis standardiseringsarbeidet skal være åpent for høringer og bredere deltakelse.
En enkel test
Hvis en standard krever omfattende muntlig forklaring for å kunne brukes likt, er dokumentasjonen sannsynligvis for svak. En god standard bør være mulig å forstå på en strukturert måte uten at alt avhenger av lokal kunnskap.
Derfor er dokumentasjon ikke pynt rundt standarden. Den er en del av selve kvaliteten.
Hvis du vil gå videre i samme temaklynge, anbefaler vi også Forskjellen på krav og veiledning i en standard , Referanseimplementasjon for standarder , Hvorfor testdata er viktig i standardarbeid og Begreper og definisjoner i økonomidata .