SoftwareudviklingTjekliste
enRead in EnglishSoftwaredokumentation: 8 dokumenter dit projekt skal have før overdragelse
Softwaredokumentation der virker i praksis: de 8 dokumenter dit projekt skal have, så en ny udvikler kan overtage uden at starte forfra.
Freelance full-stack udvikler
- Udgivet
- Læsetid
- 8 min.
Indhold i indlægget8
Softwaredokumentation er det der gør at en anden udvikler kan overtage dit system uden at ringe til den tidligere udvikler eller starte forfra. Du behøver ikke en tyk manual, men otte korte dokumenter: README, arkitekturoverblik, beslutningslog, driftsvejledning, adgangsoversigt, integrationsoversigt, administratorvejledning og en liste over kendte fejl og teknisk gæld. Tjeklisten herunder viser hvad hvert dokument skal indeholde og hvordan du tester at det holder.
Jeg tilbyder selv vedligehold og overtager projekter som andre har bygget, så læs med det forbehold. Listen er min anbefaling til hvad du bør kræve af enhver udvikler, også af mig.
Den korte version: de 8 dokumenter
| # | Dokument | Svarer på | Primært til |
|---|---|---|---|
| 1 | README | Hvordan starter jeg projektet op? | Udviklere |
| 2 | Arkitekturoverblik | Hvad består systemet af, og hvordan hænger det sammen? | Udviklere |
| 3 | Beslutningslog | Hvorfor er det bygget sådan? | Udviklere og dig |
| 4 | Driftsvejledning | Hvordan kommer ny kode i drift, og hvad gør man når noget går ned? | Udviklere |
| 5 | Adgangsoversigt | Hvilke konti findes, hvem ejer dem, og hvem betaler? | Dig |
| 6 | Integrationsoversigt | Hvilke andre systemer er koblet på, og hvilke data sendes? | Dig og udviklere |
| 7 | Administratorvejledning | Hvordan klarer I det daglige uden at ringe til udvikleren? | Dine medarbejdere |
| 8 | Kendte fejl og teknisk gæld | Hvad er ufærdigt, skrøbeligt eller udskudt? | Dig og næste udvikler |
Dokumentation er ikke en fase til sidst. Den skal skrives løbende gennem hele forløbet fra idé til drift, ellers bliver den aldrig til noget. Min tommelfingerregel er at en opgave ikke er færdig før dokumentationen er opdateret.
Dokumenterne der får en ny udvikler i gang (1-3)
De tre første er skrevet til udviklere. Du behøver ikke forstå hver linje, men du skal kunne se at de findes og passer til koden i dag.
Forstå koden
- 1. README: Filen i roden af dit repository forklarer hvad projektet er, hvad det kræver, hvordan det installeres lokalt, og hvordan testdata og automatiske tests køres. GitHub fremhæver det samme i sin vejledning om README-filer: hvad projektet gør, og hvordan man kommer i gang. Test: Kan en udvikler der aldrig har set koden, få den til at køre samme dag?
- 2. Arkitekturoverblik: En til to sider og et diagram over systemets dele: brugerflade, backend, database, køer og eksterne tjenester. C4-modellen er en udbredt måde at tegne det på. Beskriv også datamodellen og de vigtigste forretningsregler, fx hvordan en pris bliver beregnet. Test: Kan du selv pege på diagrammet og sige hvor kundedata ligger?
- 3. Beslutningslog: Korte noter om de store valg: hvorfor netop det framework, hvorfor den betalingsløsning, hvorfor en funktion blev bygget om. Formatet kaldes ofte ADR (Architecture Decision Record), som Michael Nygard beskrev i 2011: kontekst, beslutning og konsekvenser i en kort tekstfil. Test: Kan en ny udvikler se hvorfor noget mærkeligt er lavet sådan før vedkommende fjerner det?
Beslutningsloggen er typisk den der mangler. Uden den gætter næste udvikler, og så bliver gamle fejlvalg bevaret af frygt, eller en vigtig beslutning bliver rullet tilbage ved et uheld. En kravspecifikation fra projektets start hjælper, men den beskriver hvad der skulle bygges. Dokumentationen skal beskrive hvad der faktisk blev bygget.
Dokumenterne der holder systemet kørende (4-6)
De næste tre dokumenter redder dig når noget går galt en fredag eftermiddag, eller når samarbejdet med din udvikler slutter.
Drift, adgange og integrationer
- 4. Driftsvejledning: Hvordan ny kode kommer fra repository til produktion, hvilke miljøer der findes (fx et testmiljø og produktion), hvilke baggrundsjob og planlagte kørsler systemet har, hvor logs ligger, og hvordan en fejlslagen udgivelse rulles tilbage. Den skal også beskrive hvor backup ligger, og hvordan den gendannes. Test: Hvornår blev en gendannelse sidst prøvet af?
- 5. Adgangsoversigt: Alle konti systemet afhænger af: repository, hosting, domæne og DNS, mail, betaling, overvågning og eventuelle app stores. For hver konto står der hvem der ejer den, hvem der betaler, hvem der har adgang, og hvornår noget skal fornyes. Adgangskoderne selv hører hjemme i en adgangskodemanager som virksomheden ejer. Test: Står alle konti i virksomhedens navn og ikke i udviklerens?
- 6. Integrationsoversigt: De eksterne systemer der sendes data til og fra, fx regnskab, betaling eller CRM. For hver integration står der hvad der sendes, hvordan fejl opdages, og hvem der er kontakt hos leverandøren. Notér også hvilke tjenester der behandler persondata, så du kender dine databehandlere. Datatilsynet forklarer rollefordelingen mellem dataansvarlig og databehandler. Test: Ved du hvad der sker hvis en integration fejler i nat?
Adgangsoversigten afgør oftest om et udviklerskifte bliver smertefrit eller dyrt. Selve overdragelsen har jeg beskrevet i guiden til at skifte udvikler midt i et projekt.
Dokumenterne der beskytter hverdagen og budgettet (7-8)
De sidste to handler mindre om koden og mere om hvor tit du er nødt til at ringe til udvikleren, og hvor mange overraskelser du kan forvente.
Hverdag og budget
- 7. Administratorvejledning: En kort vejledning til dine medarbejdere i det de selv kan klare: oprette brugere, ændre priser og tekster, eksportere data og håndtere en refusion. En kort skærmoptagelse virker ofte bedre end tekst. Test: Ringer I til udvikleren om ting som en medarbejder burde kunne klare selv?
- 8. Kendte fejl og teknisk gæld: En ærlig liste over det der ikke er færdigt, midlertidige løsninger, kendte fejl, pakker der snart mister support, og det der bevidst er udskudt. Suppler med en ændringslog over hvad der er udgivet hvornår. Test: Kan du se det næste halve års vigtigste oprydning uden at spørge?
Punkt 8 er det dokument udviklere nødigst skriver fordi det viser svaghederne. Netop derfor er det vigtigt: teknisk gæld bliver dyrere jo længere den er skjult, og en liste gør den til noget du kan budgettere med.
Sådan tjekker du at dokumentationen holder
Du behøver ikke kunne kode for at vurdere dokumentationen. Tre tjek siger det meste:
- Se hvor den ligger. Ligger dokumenterne i dit repository som almindelige tekstfiler (typisk Markdown), eller i udviklerens egne noter? Kun det første følger med når samarbejdet slutter.
- Se på datoerne. Er README to år gammel mens koden blev ændret i sidste uge, passer den sandsynligvis ikke længere.
- Lav en fremmedtest. Betal en anden udvikler for at bruge et par timer på at starte projektet og lave en lille ændring ud fra dokumenterne alene. Der hvor vedkommende går i stå, mangler der dokumentation.
Det er billigt sammenlignet med at opdage hullerne den dag den eneste der kender systemet, ikke svarer længere. Testen passer godt ind i en bredere vurdering af om din kodebase er sund.
Hvornår du ikke skal betale for alle otte
En lille hjemmeside eller en prototype du stadig tester på brugere, har ikke brug for en beslutningslog og en administratorvejledning. Her er README og adgangsoversigt nok. Resten kan komme når systemet bliver forretningskritisk.
Betal heller ikke for et langt Word-dokument skrevet i projektets sidste uge. Det er forældet efter første ændring, og ingen åbner det. Kort dokumentation ved siden af koden slår lang dokumentation i en mappe.
Har du allerede en udvikler du er glad for, så skift ikke for at få dokumentation. Send tjeklisten, og bed om de manglende dokumenter som en fast del af arbejdet. Det er typisk et spørgsmål om timer eller få dage, ikke et nyt projekt.
Næste skridt
- Gå tabellen igennem, og marker hvilke af de otte dokumenter du kan finde i dag.
- Start med adgangsoversigten. Den kan du langt hen ad vejen lave selv ud fra dine fakturaer og kreditkortudtog.
- Bed din udvikler om resten i prioriteret rækkefølge, og gør dokumentation til en del af hver opgave fremover.
Har du ingen der holder dit system ved lige, eller forsvandt dokumentationen med en tidligere udvikler, kan du se hvordan jeg arbejder med vedligehold og videreudvikling. Du ejer koden fra første dag og taler direkte med den udvikler der skriver den.
Ofte stillede spørgsmål
Hvem skal betale for dokumentationen?
Det gør du, men den bør være regnet med i prisen fra starten og ikke komme som en ekstraregning til sidst. Dokumentation skrevet løbende tager kort tid fordi udvikleren har detaljerne frisk i hukommelsen. Skal en ny udvikler rekonstruere den bagefter, tager det typisk langt længere tid, og regningen lander stadig hos dig.
Kan jeg kræve dokumentation i kontrakten?
Ja, og det bør du. Skriv dokumentationen ind som en leverance med en konkret liste, fx de otte dokumenter her, og aftal at den opdateres løbende og overdrages sammen med koden. Uden en skriftlig aftale er den svær at kræve bagefter. Det her er ikke juridisk rådgivning, så få kontrakten gennemgået hvis der står meget på spil.
Er koden ikke dokumentation nok i sig selv?
Kun delvist. Læsbar kode og automatiske tests viser hvad systemet gør. Men koden fortæller ikke hvorfor noget blev valgt, hvilke konti der findes, hvem der betaler for hostingen, eller hvordan du gendanner en backup. Det skal stå et sted hvor både du og næste udvikler kan finde det.
Hvad gør jeg hvis min udvikler ikke vil dokumentere?
Spørg først hvorfor. Ofte er svaret tid, og så kan I aftale et fast antal timer om måneden til det. Afviser udvikleren helt, er det et advarselstegn fordi du så er afhængig af én persons hukommelse. Få i det mindste adgangsoversigten og README på plads mens samarbejdet fungerer.