Mange kan være enig i at dokumentasjon er bra, og dokumentasjon er viktig. Men hva trenger vi å dokumentere, og hvordan skal vi skrive og forvalte dokumentasjon på en god måte?

En gang i tiden kunne det ta timer eller døgn å teste programvare. Under slike forutsetninger har man ikke alltid tid til å teste noe for å sjekke om det virker, man trenger kvalitetssikring før man programmerer og tester. God og grundig dokumentasjon er verktøyet som legger til rette for dette.

Så kom «the agile manifesto» som kan ses på som en reaksjon på dette: «working software over comprehensive documentation». I dag (og i hvert fall de siste 25 årene) er det ofte raskere å skrive og teste kode enn det er å skrive dokumentasjon. Det kan være bedre bruk av tid å skrive oversiktlig og velfungerende kode med automatiske tester enn å skrive dokumentasjon.

Men dette er ikke hele historien. Ikke alt er selvforklarende, og ikke alle har mulighet til å se på kode for å forstå hvordan den fungerer, og det vil være overordnede spørsmål om mål, valg, modeller og abstraksjoner, sammenhenger og antagelser som ikke gir seg selv.

I dagens «API economy», økosystemer av offentlige tjenester, data-drevne innovasjon, *-as-a-Service og plattform-modeller vil vi påstå at dokumentasjon er ekstremt viktig. Ingen klarer å gjette seg til hvordan alt dette fungerer og hvordan man skal få det til å henge sammen, uten presis, oppdatert og lettlest dokumentasjon.

I denne artikkelen vil vi utforske noen dimensjoner som påvirker hvorfor vi trenger dokumentasjon, hva vi trenger den til og hvordan vi skal lage og forvalte den.

Hvorfor trenger vi dokumentasjon?

Uten at vi skal gå helt tilbake til begynnelsen og argumentere for skrift som grunnlaget for all sivilisasjon, er det naturlig å trekke frem noen generelle momenter:

• Ting som er skrevet ned slipper man å gå rundt og huske på, og det utgjør også en felles hukommelse mellom leserne.
• Kunnskap som er skrevet ned er mulig å referere til, enkelt å overføre og et grunnlag for å samarbeide om forbedringer.
• Når føringer, krav og rammebetingelser er skrevet ned er det mulig å kvalitetssikre det som gjøres opp mot en felles kilde, som er en forutsetning for å levere konsistent kvalitet.

Anna (27): - Oversiktlig versjons­historikk varmer meg langt inn i hjerterota

mandag 21. mars 2022

Men det betyr selvsagt ikke at alt er enkelt og greit bare det er skrevet ned:

• Tolkning og forståelse av innholdet i en tekst er avhengig av leserens kontekst, antagelser og forkunnskaper.
• Det hjelper ikke om ting er skrevet ned, hvis man ikke vet hvordan man finner frem, eller kanskje man ikke en gang vet om at noe finnes.
• At ting er skrevet ned betyr ikke at det er riktig, oppdatert, gjeldende og at det er enighet.

Utfra dette kan man gjøre seg noen betraktninger om hva dokumentasjonen skal brukes til. To generelle bruksområder kan være hva vi kan kalle transaksjonsdokumentasjon og beskrivelsesdokumentasjon.

Transaksjonsdokumentasjon er dokumentasjon av noe vi er enige om skal gjøres og som beskriver dette, men som ikke blir vedlikeholdt etter at det er gjort. Et eksempel er en bestilling som er relevant underveis, men etter at man har levert er det bare interessant som en form for loggføring av hva som har skjedd.

Beskrivelsesdokumentasjon på den annen side er en beskrivelse av hvordan noe fungerer nå eller hvordan man skal forholde seg til en ting. Dette er dokumentasjon som må oppdateres i takt med at situasjonen endres. Eksempel på dette er en brukerveiledning eller teknisk API-dokumentasjon. Dette må vedlikeholdes i takt med at produktet utvikles.

- Forstår de ikke koden din, er den for dårlig

fredag 21. august 2020

Hvem skriver vi for?

Et annet spørsmål som er viktig er hvem dokumentasjonen er til for. Er det for de som skal bruke systemet, for de som skal lage systemet, eller for noen andre? For eksempel: alle sky-plattformen tilbyr at API-applikasjoner kan bruke for å få tilgang til tjenester i plattformen, slik som lagring, kommunikasjon, skalering osv.

Applikasjonsutviklere som skal bruke plattformen trenger dokumentasjon av hvordan disse API-ene skal brukes, hva som er input, forventet resultat, forventet ytelse, mulige feilsituasjoner osv.

På den annen side, de som skal lage og videreutvikle plattformen trenger en helt annen dokumentasjon som beskriver hvordan noe er løst på innsiden.

En åpenbar forskjell her er at de som ser et produkt fra utsiden trenger en beskrivelse av hva produktet gjør og hvordan det brukes, mens de som skal forvalte og videreutvikle også trenger beskrivelse av hvordan det er laget og hvorfor det er laget på denne måten. Men en vel så viktig forskjell er at de som forvalter produktet har direkte tilgang til personer de kan snakke med for å forstå.

Det betyr at kravene til presisjon, struktur, lesbarhet og at dokumentasjon er oppdatert er mye høyere på utsiden enn på innsiden. Det er selvsagt variasjoner også her. For brukergrensesnitt er det et mål at de skal være mest mulig selvforklarende, og sluttbrukeren skal slippe å lese dokumentasjon for å klare å bruke systemet, og det er kanskje et poeng i seg selv at man skal skrive minst mulig dokumentasjon.

Hanne håper vi blir flinkere på dokumentasjon

torsdag 21. mars 2019

Bruksområder

Over har vi sett på to dimensjoner av dokumentasjon: hva den skal brukes til og hvem den skal brukes av. Med dette som rammeverk kan vi se på ulike bruksområder og beskrive krav til dokumentasjon i ulike sammenhenger:

I modellen ovenfor er det rimelig å stille høyere krav til kategori 3 og 4. Dette er dokumentasjon som skal fungere som kommunikasjonsverktøy mellom grupper som ikke jobber tett sammen, kanskje ikke snakker sammen i det hele tatt og som kanskje kommer fra forskjellige fagfelt.

I motsetning til 1 og 2 som typisk brukes internt i et team hvor man har felles språk og referansemodeller og alltid har mulighet til å snakke med noen for avklaringer. Samtidig vil kategori 2 og 4 være viktigere enn 1 og 3, fordi dette skal leve over lenger tid og må tåle å bli brukt i andre sammenhenger enn da de ble skrevet.

Noen eksempler på dokumentasjon innen hver gruppe:

1. Hvilke vurderinger som er gjort og valg som er tatt i utviklingsprosessen. Design-skisser, testrapporter, endringsforespørsler, estimater. Dette er relevant for å kunne samle erfaringer over tid og for å slippe å gjenta utredninger som allerede har vært gjort.
2. Klassediagram, moduler, avhengigheter, filformater, interne API osv. Alt en utvikler kan tenkes å lure på i sitt arbeid. Dette trenger dog ikke være mer presis eller oppdatert enn at leseren forstår omtrent hvordan ting henger sammen, hvor man skal finne mer informasjon og hvem man kan snakke med.
3. Behovsbeskrivelser, brukerhistorier, tekniske krav, feilrapporter osv. Hvor detaljert og presis dette trenger å være er avhengig av hvem brukerene er, hvilken dialog man har med utviklere underveis og hvilken type system som utvikles. Det stilles andre krav til bremsesystemet i en bil enn til radioen.
4. API-dokumentasjon, brukerdokumentasjon, sikkerhetskrav, SLA. Som for punkt 3 vil dette også være avhengig av hvem som er brukerene og type system. Dette er kanskje den viktigste dokumentasjonen, fordi denne er en forutsetning for riktig bruk av systemet, og skal leses av personer som kanskje ikke har alternative kilder til kunnskap.

Urte (26) ville lære barn å kode, men kunne ikke kode selv: - De gjennomskuet meg

onsdag 29. juni 2022

Oppsummert

Dokumentasjon er viktig, men dokumentasjon som ikke blir lest og forstått har ingen verdi, det samme gjelder dokumentasjon som er feil eller misvisende.

Det er derfor viktig å tenke på hvem man dokumenterer for, hva leseren skal få ut av dokumentasjonen og hvordan den skal vedlikeholdes.

Den kanskje viktigste dokumentasjonen er det som er ment som permanent dokumentasjon av hvordan et system brukes, for brukere som ikke selv er en del av forvaltning og videreutvikling.

Sliter du med å skrive readme-filer? Ikke med denne malen!

onsdag 13. april 2022