Hopp til innhold

Satte dokumentasjonen under sin egen linter — et linjebudsjett per fil som bare kan strammes inn, et krav om indeks og en kontroll av reelle stier — som fant seks av ni planer merket som ferdige med uavkryssede bokser, og fjorten commit‑sperrende oppgaver som ikke var nevnt i noe dokument.

dokumentasjonen lagt under sin egen linter

Situasjon. Repoet styrer seg selv med skriftlige instrukser — tjueseks dokumenter som dekker kvalitetspolicyen, designsystemet, universell utforming, utskrift, metadata, oversettelse og git. Instrukser har et bestemt forfallsmønster: de blir lengre, de glir bort fra koden, de begynner å vise til filer som er flyttet, og ved en viss størrelse slutter de å bli lest. En regel som ikke blir lest, er ingen regel.

Oppgave. Dokumentasjonen trengte samme behandling som koden — en linter med grenser som feiler i stedet for å gi råd.

Handling. Åtte policyer, alle mekaniske. Et hardt tak på dokumentlengde og et mykere som advarer. Et linjebudsjett per fil som bare kan skrus nedover, så et dokument kan krympe, men ikke vokse igjen. Et krav om indeks over en viss terskel, og om en seksjonsindeks over en lavere. En plasseringsregel om hvilket dokument som eier hvilket emne. Gyldige lenker. Ærlige planer — statusen en plan oppgir, må stemme med dens egne avkrysningsbokser. En regel om at hver oppgave en commit må gjennom, er nevnt i et eller annet dokument. Og en kontroll av reelle stier: at hver katalogkvalifisert sti og hvert kodesymbol et dokument nevner, faktisk finnes. Den første kjøringen var argumentet for hele øvelsen: seks planer merket som ferdige med uavkryssede bokser, fjorten oppgaver som hver commit måtte gjennom og som ikke var nevnt i noe dokument i det hele tatt, tre ødelagte lenker, ett foreldreløst dokument og tre døde stier fordelt på fem dokumenter. Budsjettet avviste deretter sin egen forfatter — å skrive oppsummeringen av dette arbeidet inn i utviklingsdokumentet presset det over grensen, og slik oppsto et eget dokument, og det er nettopp slik policyen er ment å virke.

Resultat. Tjueseks dokumenter på til sammen omtrent 2 666 effektive linjer, hvert under et budsjett som ikke kan vokse, med hver sti og hvert symbol de nevner kontrollert mot treet. Det ubehagelige funnet er det som er verdt å gjenta: fjorten kontroller sto som port for hver eneste commit uten å stå i noe dokument, så reglene maskinen håndhevet og reglene menneskene leste, hadde allerede skilt lag.

Ett stykke av en lengre oversikt — og den ligger i sin helhet her.

Hver oppføring er skrevet på samme måte: situasjonen, oppgaven, hva vi gjorde, og hva som endret seg.

Se hele oversikten