Hvilken dokumentasjon har du rett til å kreve?

Dokumentasjon er den delen av et utviklingsprosjekt som alle sier at de vil ha, og som ingen vil betale for. Kunder frykter enten tykke permer som ingen leser, eller en kodebase så udokumentert at den blir umulig å ta over. Sannheten ligger midt imellom: Du har rett til å kreve dokumentasjon, men det finnes et passe nivå. For mye er sløsing, for lite er innlåsing. Slik finner du riktig nivå og sørger for at dokumentasjonen faktisk blir levert.

Passe nivå: Hva er målestokken?

Den eneste meningsfulle målestokken for dokumentasjon er praktisk: Kan en ny utvikler som aldri har sett systemet, sette seg inn i det uten å måtte spørre den som bygde det? Klarer en utenforstående å forstå hvordan systemet henger sammen, hvordan det kjøres og hvordan man bygger videre på det, er dokumentasjonen tilstrekkelig.

Alt utover det risikerer å bli noe som ingen leser og ingen oppdaterer. Detaljerte dokumenter som beskriver hver funksjon med ord, blir utdaterte i samme øyeblikk som koden endres, og da er de verre enn ingenting: De villeder. Sikt derfor mot nytteverdi fremfor volum. En kort, korrekt beskrivelse slår en lang, utdatert beskrivelse hver gang.

Poenget med dokumentasjonen er uavhengighet. Så lenge bare den som skrev koden, forstår den, er du låst til den personen eller leverandøren. Dokumentasjonen er det som gjør at systemet kan overleveres.

Minimumspakken

Fire dokumenttyper dekker det meste av behovet. Har du disse, er du rustet for de vanligste situasjonene: at en ny person skal ta over, at systemet skal feilsøkes eller produksjonssettes, og at et annet system skal kobles på.

Arkitekturskissen er den viktigste og den mest forsømte. Den trenger ikke å være pen. Et enkelt bilde som viser de store delene og hvordan de snakker sammen, kommer man langt med, og det sparer den nye utvikleren for dager med gjetting. Driftsdokumentasjonen er den som er vond å være uten klokken tre om natten når noe har gått ned og ingen husker hvordan systemet startes på nytt.

Levende dokumentasjon i repoet

Hvor dokumentasjonen ligger, avgjør om den holder seg oppdatert. Separate dokumenter i en mappe ved siden av koden lever sitt eget liv og slutter raskt å stemme fordi de oppdateres i en annen arbeidsflyt enn koden. Dokumentasjon som ligger i repoet, oppdateres derimot samtidig som koden endres, og holdes derfor levende.

En fornuftig arbeidsdeling er å la det løpende (hvordan man bygger, kjører og kaller systemet) ligge nær koden i repoet, mens et overordnet arkitekturbilde kan ligge som et eget dokument som gjennomgås med jevne mellomrom. Målet er at oppdatering skal være en naturlig del av arbeidet, ikke en separat oppgave som alltid blir glemt. Det som krever ekstra innsats å holde oppdatert, blir sjelden oppdatert.

Skriv kravet inn i Definition of Done og avtalen

Det som ikke kreves, blir nedprioritert så snart tiden blir knapp, og tiden blir alltid knapp mot slutten. Derfor holder det ikke å ønske seg dokumentasjon. Den må være et leveransekrav.

Den kan gjøres obligatorisk på to steder. I Definition of Done, teamets felles definisjon av hva «ferdig» betyr, skriver du inn at en funksjon ikke er ferdig før den er dokumentert. Da bygges dokumentasjonen fortløpende i stedet for å bli skjøvet til en sluttfase som sjelden blir noe av. I avtalen regulerer du minimumspakken som en del av leveransen slik at du har noe å stå på hvis den uteblir.

Et scenario: overleveringen som ikke gjorde vondt

Et selskap byttet utviklingsleverandør etter tre år. Fordi det gamle teamet fra starten hadde hatt dokumentasjon skrevet inn i Definition of Done, fantes det en oppdatert arkitekturskisse, en README som fungerte, og driftsdokumentasjon i repoet. Det nye teamet var i gang i løpet av en ukes tid.

Et annet selskap i samme situasjon, men uten dokumentasjonskrav, måtte i stedet betale den gamle leverandøren dyrt for en lang kunnskapsoverføring og gjette seg frem der hukommelsen sviktet. Forskjellen var ikke dyktigere utviklere, men at det ene selskapet hadde krevd dokumentasjon fra starten.

Vil du finne et dokumentasjonsnivå for prosjektet ditt som er tilstrekkelig, men ikke overdrevet, hjelper vi i Weapp gjerne til. En teknisk gjennomgang viser også raskt hvor lett et eksisterende system faktisk kan overleveres.