Vilken dokumentation har du rätt att kräva?

Dokumentation är den del av ett utvecklingsprojekt som alla säger sig vilja ha och ingen vill betala för. Beställare fruktar antingen tjocka pärmar som ingen läser, eller en kodbas så odokumenterad att den blir omöjlig att ta över. Sanningen ligger i mitten: du har rätt att kräva dokumentation, men det finns en lagom nivå. För mycket är slöseri, för lite är en inlåsning. Här är hur du hittar rätt och ser till att den faktiskt levereras.

Lagom nivå: vad är måttet?

Det enda meningsfulla måttet på dokumentation är praktiskt: kan en ny utvecklare som aldrig sett systemet komma in i det utan att behöva fråga den som byggde det? Klarar en utomstående att förstå hur systemet hänger ihop, hur det körs och hur man bygger vidare på det, så är dokumentationen tillräcklig.

Allt utöver det riskerar att bli sådant som ingen läser och ingen uppdaterar. Detaljerade dokument som beskriver varje funktion i ord blir inaktuella i samma stund koden ändras, och då är de värre än inget – de vilseleder. Sikta därför på användbarhet framför volym. En kort, korrekt beskrivning slår en lång, föråldrad varje gång.

Poängen med dokumentationen är oberoende. Så länge bara den som skrev koden förstår den är du inlåst hos den personen eller leverantören. Dokumentationen är det som gör systemet överlämningsbart.

Minimipaketet

Fyra dokumenttyper bär det mesta av behovet. Har du dessa täcker du de vanligaste situationerna: att någon ny ska ta över, att systemet ska felsökas eller driftsättas, att ett annat system ska kopplas på.

Arkitekturskissen är den viktigaste och den mest försummade. Den behöver inte vara vacker – en enkel bild som visar de stora delarna och hur de pratar med varandra räcker långt, och den sparar den nye utvecklaren dagar av gissande. Driftdokumentationen är den som gör ont att sakna klockan tre på natten när något har gått ner och ingen minns hur systemet startas om.

Levande dokumentation i repo

Var dokumentationen bor avgör om den håller sig aktuell. Separata dokument i en mapp vid sidan av koden lever sitt eget liv och slutar snabbt stämma, eftersom de uppdateras i ett annat flöde än koden. Dokumentation som ligger i kodrepot uppdateras däremot i samma rörelse som koden ändras och hålls därför levande.

En rimlig ordning är att låta det löpande – hur man bygger, kör och anropar systemet – bo nära koden i repot, medan en översiktlig arkitekturbild kan ligga som eget dokument som ses över med jämna mellanrum. Målet är att uppdatering ska vara en naturlig del av arbetet, inte en separat uppgift som alltid glöms bort. Det som kräver extra ansträngning att hålla aktuellt blir sällan aktuellt.

Skriv in kravet i Definition of Done och avtal

Det som inte krävs blir nedprioriterat så fort tiden tryter, och tiden tryter alltid mot slutet. Därför räcker det inte att önska sig dokumentation – den måste vara ett leveranskrav.

Två platser gör den obligatorisk. I Definition of Done, teamets gemensamma definition av vad “klart” betyder, skriver du in att en funktion inte är färdig förrän den är dokumenterad. Då byggs dokumentationen löpande i stället för att skjutas till ett slutskede som sällan blir av. I avtalet reglerar du minimipaketet som en del av leveransen, så att det finns en grund att stå på om det uteblir.

Ett scenario: överlämningen som inte gjorde ont

Ett bolag bytte utvecklingsleverantör efter tre år. Eftersom det gamla teamet från början haft dokumentation inskriven i sin Definition of Done fanns en aktuell arkitekturskiss, en README som fungerade och driftdokumentation i repot. Det nya teamet var i gång på någon vecka.

Ett annat bolag i samma läge, men utan dokumentationskrav, fick i stället betala den gamla leverantören dyrt för en lång kunskapsöverföring – och gissa sig fram där minnet svek. Skillnaden var inte skickligare utvecklare, utan att den ena hade krävt dokumentation från början.

Vill du sätta en rimlig dokumentationsnivå för ditt projekt, tillräcklig men inte överdriven, hjälper vi på Weapp gärna till – och en teknisk genomgång visar snabbt hur överlämningsbart ett befintligt system faktiskt är.