Hopp til innhold

La dokumentasjonen under sin egen linter

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.

  • Skriveblokk, hånd, skriveplate med klemme
    Foto: Mohamed_hassan / Pixabay
  • Dokumenter, papirer
    Foto: Tomasz_Mikolajczyk / Pixabay

Bruk erfaringen i prosjektet deres

Bruk «La dokumentasjonen under sin egen linter» som utgangspunkt for en lignende utfordring i organisasjonen deres. Tjenestene bak arbeidet er tilgjengelige for prosjektet deres. Noen på din side av bordet når en leverandør, et budsjett eller en arkitekturbeslutning trenger en ny, kyndig vurdering.

Se tjenestene våre Ta kontakt

Se bak resultatet

Les om situasjonen, beslutningene og resultatet i eksemplet. Vi kan drøfte hva som passer deres rammer, og hva som krever en annen tilnærming. La dokumentasjonen under sin egen linter — dokumentasjonen lagt under sin egen linter

Se tjenestene våre Ta kontakt

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

Definer forbedringen dere trenger

Ta med beslutningen, menneskene som berøres og alternativene som er vurdert. Vi kan tydeliggjøre avveiningene og etterlate en dokumentert anbefaling.

Se hva det koster Ta kontakt

Blir dokumentasjonen din utdatert uten at noen merker det?

Spør om beslutningene bak «La dokumentasjonen under sin egen linter». Dere snakker med folk som kan forklare arbeidet og vurdere deres eget prosjekt.

Se tjenestene våre
welcome@engineer.company +45 50 10 61 84 København, Danmark
QR-kode for 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.
Ta med deg denne sidenhttps://advisory.engineer.company/nb/portfolio/put-the-documentation-under-its-own-linter/