Få kodedokumentasjon skrevet underveis

Utfordringen

Dokumentasjon blir ofte utsatt til etter lansering, når utviklerne allerede har gått videre. Nye kolleger og andre team må da lese kode eller spørre rundt for å forstå grensesnitt, valg og avhengigheter i løsningen og vedlikeholdet.

Slik kommer dere i gang

1. 1

   Velg hva som skal dokumenteres

   Start med en modul, et API eller en vanlig utviklingsoppgave. Avklar hvem dokumentasjonen er for og hvor den skal ligge. Lag en enkel mal for formål, oppsett, parametere, eksempler og kjente begrensninger.

2. 2

   Lag utkast fra kodeendringen

   La AI-verktøyet foreslå forklaringer og eksempler basert på den aktuelle endringen. Be om referanser til filer og funksjoner, og hold utkastet nært koden. Skriv ikke inn hemmeligheter, testdata med personopplysninger eller udokumenterte antakelser.

3. 3

   Test og godkjenn dokumentasjonen

   Utvikleren skal kjøre eksemplene, rette utydelige beskrivelser og kontrollere at teksten stemmer med versjonen som publiseres. Menneskelig gjennomgang er siste kontroll før dokumentasjonen merges sammen med koden.

Slik ser det ut i praksis

Et utviklingsteam fikk 80 prosent flere endepunkter dokumentert som en naturlig del av utviklingsflyten. Dette er et illustrativt eksempel, og en ansvarlig medarbeider må kontrollere grunnlaget og resultatet før det brukes videre i praksis.

Verktøy

Cursor, Claude Code og GitHub Copilot kan lese kodeendringer og foreslå beskrivelser, kommentarer og eksempler der utvikleren arbeider. De passer godt som skrivehjelp i repoet. Versjonskontroll, testing, kvalitetssikring, faglig kontroll og kodegjennomgang gjør det mulig å holde dokumentasjonen internt alltid knyttet til riktig kodeversjon.

Fallgruver å unngå

• Dokumentasjon som ser ryddig ut kan beskrive gammel eller feil oppførsel. Test alltid kodeeksempler og oppdater teksten i samme endring som funksjonen.
• AI kan fylle hull med antakelser når koden er uklar. Be om korte, kildebaserte utkast og la utvikleren skrive inn begrunnelser og begrensninger.
• Hvis dokumentasjonen ligger utenfor repoet, er det lett at den blir glemt. Versjoner den sammen med koden og gjør gjennomgang til en del av pull requesten.