Jag ägnade en förmiddag åt att ta bort saker ur dokumentationen. Ingen ny funktion, ingen buggfix — bara raderade stycken.
Det var förmodligen den nyttigaste förmiddagen den månaden.
Servern som inte fanns
I dokumentationen fanns en virtualiseringsvärd beskriven i detalj: adress, inloggning, hur man ansluter, en felsökningsguide för dess lagring.
Servern var avvecklad. Den hade inte funnits på månader.
Det låter ofarligt. Det är det inte, och skälet är värt att stanna vid: dokumentation som beskriver något som inte finns är sämre än ingen dokumentation alls. Ingen dokumentation gör att man frågar någon. Felaktig dokumentation gör att man agerar.
Föreställ dig den som ska felsöka lagring klockan tre på natten, läser den där guiden och börjar leta efter en värd som inte existerar. Nu är felsökningen två problem: det ursprungliga, plus förvirringen över varför ingenting stämmer.
Det gäller i ännu högre grad när det är en agent som läser. En modell som får dokumentationen som underlag ifrågasätter inte om servern finns — den planerar utifrån att den gör det. Föråldrad dokumentation blir instruktioner.
Det som saknades var farligare
Under städningen dök en annan sak upp. Backupservern hämtar sitt lagringsutrymme från en nätverkslagringsenhet som stod odokumenterad — den fanns i nätet, den hade en adress, och ingenstans stod det vad den gjorde.
Alltså: en enhet som ser ut som något man kan stänga av vid städning, men som i praktiken håller hela backuplösningen. Den sortens kunskap sitter i en persons huvud tills den dagen personen är på semester.
Nu står det i dokumentationen, med versaler: den här får inte stängas av, och det här är varför.
Samtidigt kopplades en gammal lagringsenhet bort ur klustret — kontrollerat, efter att jag verifierat att ingen virtuell disk faktiskt låg på den. Skillnaden mellan de två enheterna var noll ur nätverkets perspektiv och total ur verksamhetens.
Så vet du att det funkar
Läs dokumentationen som en främling. Ta en sida i taget och fråga: finns det här fortfarande? Svarar du ”jag tror det” är svaret nej tills du kontrollerat.
Gå åt andra hållet också. Lista vad som faktiskt svarar i nätet och jämför mot dokumentationen. Det som finns men inte är beskrivet är farligare än det som är beskrivet men inte finns.
Skriv ner vad som inte får röras, och varför. ”Får ej stängas av” utan orsak kommer att ignoreras av någon som har bråttom. Med orsak överlever den.
Vad jag tar med mig
Dokumentation ruttnar snabbare än kod, eftersom ingenting kompilerar den. En felaktig rad i ett program märks; en felaktig rad i en beskrivning ligger kvar och ser lika trovärdig ut som resten.
Att stryka är därför lika mycket underhåll som att skriva. Jag hade lagt tid på att lägga till beskrivningar i flera år utan att en enda gång gå igenom och ta bort. Det är inte hållbart — och det är en sysselsättning som lämpar sig utmärkt för en tråkig förmiddag i mars.