Hvilken dokumentation har du ret til at kræve?
Du har ret til at kræve den dokumentation der gør at en ny udvikler kan overtage systemet uden at gætte. Minimumspakken er en arkitekturskitse, driftsdokumentation, en README og API-dokumentation. Sigt efter levende dokumentation i repoet frem for separate ringbind som ingen opdaterer, og skriv kravene ind i Definition of Done og aftalen så de faktisk bliver leveret.
Dokumentation er den del af et udviklingsprojekt som alle siger de gerne vil have, og som ingen vil betale for. Kunder frygter enten tykke ringbind som ingen læser, eller en kodebase der er så udokumenteret at den bliver umulig at overtage. Sandheden ligger i midten: Du har ret til at kræve dokumentation, men der findes et passende niveau. For meget er spild, for lidt er lock-in. Her kan du se hvordan du rammer rigtigt og sørger for at den faktisk bliver leveret.
Det passende niveau: Hvad er målestokken?
Den eneste meningsfulde målestok for dokumentation er praktisk: Kan en ny udvikler der aldrig har set systemet, komme ind i det uden at skulle spørge den der byggede det? Kan en udefrakommende forstå hvordan systemet hænger sammen, hvordan det køres og hvordan man bygger videre på det, så er dokumentationen tilstrækkelig.
Alt ud over det risikerer at blive noget som ingen læser og ingen opdaterer. Detaljerede dokumenter der beskriver hver funktion i ord, bliver forældede i samme øjeblik koden ændres, og så er de værre end ingenting: De vildleder. Sigt derfor efter anvendelighed frem for mængde. En kort, korrekt beskrivelse slår en lang, forældet hver gang.
Pointen med dokumentationen er uafhængighed. Så længe kun den der skrev koden, forstår den, er du låst fast hos den person eller leverandør. Dokumentationen er det der gør det muligt at overdrage systemet.
Minimumspakken
Fire dokumenttyper dækker det meste af behovet. Med dem er du godt rustet til de mest almindelige situationer: at en ny person skal overtage, at systemet skal fejlsøges eller idriftsættes, at et andet system skal kobles på.
| Dokument | Hvad det skal besvare |
|---|---|
| Arkitekturskitse | Hvordan hænger systemets dele sammen, og hvorfor? |
| Driftsdokumentation | Hvordan køres og idriftsættes systemet, og hvad gør man ved fejl? |
| README | Hvordan får en ny udvikler udviklingsmiljøet op at køre? |
| API-dokumentation | Hvordan kalder andre systemer grænsefladerne, og hvad kommer der tilbage? |
Arkitekturskitsen er den vigtigste og den mest forsømte. Den behøver ikke at være pæn. En enkel tegning der viser de store dele og hvordan de taler sammen, rækker langt og sparer den nye udvikler for dages gætteri. Driftsdokumentationen er den det gør ondt at mangle klokken tre om natten når noget er gået ned og ingen kan huske hvordan systemet startes igen.
Levende dokumentation i repoet
Hvor dokumentationen ligger, afgør om den forbliver aktuel. Separate dokumenter i en mappe ved siden af koden lever deres eget liv og holder hurtigt op med at passe fordi de opdateres i et andet flow end koden. Dokumentation der ligger i repoet, bliver derimod opdateret i samme bevægelse som koden ændres og holdes derfor levende.
En fornuftig orden er at lade det løbende, altså hvordan man bygger, kører og kalder systemet, ligge tæt på koden i repoet mens et overordnet arkitekturbillede kan ligge som et selvstændigt dokument der gennemgås med jævne mellemrum. Målet er at opdatering skal være en naturlig del af arbejdet og ikke en separat opgave som altid bliver glemt. Det der kræver en ekstra indsats at holde aktuelt, bliver sjældent aktuelt.
Skriv kravet ind i Definition of Done og aftalen
Det der ikke kræves, bliver nedprioriteret så snart tiden bliver knap, og tiden bliver altid knap mod slutningen. Derfor er det ikke nok at ønske sig dokumentation. Den skal være et leverancekrav.
To steder gør den obligatorisk. I Definition of Done, teamets fælles definition af hvad “færdig” betyder, skriver du ind at en funktion ikke er færdig før den er dokumenteret. Så bliver dokumentationen lavet løbende i stedet for at blive skubbet til en slutfase som sjældent bliver til noget. I aftalen regulerer du minimumspakken som en del af leverancen så der er et grundlag at stå på hvis den udebliver.
Et scenarie: overdragelsen der ikke gjorde ondt
En virksomhed skiftede udviklingsleverandør efter tre år. Fordi det gamle team fra starten havde haft dokumentation skrevet ind i sin Definition of Done, fandtes der en aktuel arkitekturskitse, en README der virkede, og driftsdokumentation i repoet. Det nye team var i gang på en uges tid.
En anden virksomhed i samme situation, men uden krav om dokumentation, måtte i stedet betale den gamle leverandør dyrt for en lang vidensoverførsel og gætte sig frem hvor hukommelsen svigtede. Forskellen var ikke dygtigere udviklere, men at den ene havde krævet dokumentation fra starten.
Vil du fastsætte et rimeligt dokumentationsniveau for dit projekt, tilstrækkeligt, men ikke overdrevet, hjælper vi i Weapp gerne. Og en teknisk gennemgang viser hurtigt hvor let et eksisterende system faktisk er at overdrage.
Ofte stillede spørgsmål
Hvor meget dokumentation er passende?
Præcis så meget at en ny udvikler kan komme ind i systemet uden at skulle spørge den der byggede det. Mere end det bliver ofte ringbind som ingen læser og ingen opdaterer. Målestokken er praktisk, ikke kvantitativ: Kan en person der aldrig har set koden, forstå hvordan den hænger sammen, drives og bygges, så er det nok. Sigt efter anvendelighed, ikke mængde.
Hvad indgår i en rimelig minimumspakke?
Fire ting dækker det meste: en arkitekturskitse der viser hvordan delene hænger sammen, driftsdokumentation der beskriver hvordan systemet køres og idriftsættes, en README der får en ny udvikler i gang, og API-dokumentation for de grænseflader andre systemer taler med. Har du dem, dækker du de mest almindelige behov ved overdragelse og fejlsøgning.
Er dokumentation i koden bedre end separate dokumenter?
Som regel ja. Dokumentation der ligger i repoet sammen med koden, opdateres i samme flow som koden og holdes derfor levende mens separate dokumenter hurtigt bliver forældede. Et arkitekturoverblik skal alligevel ofte ligge som et selvstændigt dokument, men det løbende, altså hvordan man bygger, kører og kalder systemet, har bedst af at ligge tæt på den kode det beskriver.
Hvordan sikrer vi at dokumentationen faktisk bliver leveret?
Ved at gøre den til et leverancekrav og ikke et håb. Skriv ind i Definition of Done at en funktion ikke er færdig før den er dokumenteret, og regulér minimumspakken i aftalen. Dokumentation der ikke kræves, bliver næsten altid nedprioriteret når tiden bliver knap. Krav og opfølgning er det der gør forskellen mellem tænkt og reel dokumentation.