Har sat dokumentationen under sin egen linter

Situation. Repositoryet styrer sig selv med skrevne instruktioner — seksogtyve dokumenter, der dækker kvalitetspolitikken, designsystemet, tilgængelighed, print, metadata, oversættelse og git. Instruktioner forfalder efter et bestemt mønster: de bliver længere, de glider væk fra koden, de begynder at henvise til filer, der er flyttet, og ved en vis størrelse holder de op med at blive læst. En regel, der ikke bliver læst, er ikke en regel.

Opgave. Dokumentationen havde brug for samme behandling som koden — en linter med grænser, der får noget til at fejle og ikke bare giver råd.

Handling. Otte politikker, alle mekaniske. Et hårdt loft over dokumentlængden og et blødere, der advarer. Et linjebudget pr. fil, der kun nogensinde strammes, så et dokument kan skrumpe, men ikke vokse igen. Et krav om indeks over en tærskel og et afsnitsindeks over en mindre. En placeringsregel for, hvilket dokument der ejer hvilket emne. Gyldige links. Ærlige planer — den status, en plan påstår, skal svare til dens egne afkrydsningsfelter. En regel om, at hver opgave, der spærrer for et commit, er nævnt i et eller andet dokument. Og et tjek af reelle stier: at hver sti med mappe og hvert kodesymbol, et dokument nævner, også findes. Den første kørsel var argumentet for hele øvelsen: seks planer markeret som færdige, selvom de havde felter, der ikke var krydset af, fjorten opgaver, der spærrede for hvert commit og ikke var nævnt i noget dokument overhovedet, tre ødelagte links, ét forældreløst dokument og tre døde stier fordelt på fem dokumenter. Budgettet afviste derefter sin egen forfatter — da sammendraget af dette arbejde blev skrevet ind i udviklingsdokumentet, kom det over sin grænse, og det er sådan, et særskilt dokument opstod, hvilket er præcis sådan, politikken skal virke.

Resultat. Seksogtyve dokumenter med i alt omkring 2.666 effektive linjer, hvert under et budget, der ikke kan vokse, og hver sti og hvert symbol, de nævner, er tjekket mod træet. Det ubehagelige fund er det, der er værd at gentage: fjorten tjek spærrede for hvert eneste commit uden at optræde i noget dokument, så de regler, maskinen håndhævede, og de regler, menneskene læste, var allerede gledet fra hinanden.