Jag \u00e4gnade en f\u00f6rmiddag \u00e5t att ta bort saker ur dokumentationen. Ingen ny funktion, ingen buggfix \u2014 bara raderade stycken.<\/p>\n\n\n\n
Det var f\u00f6rmodligen den nyttigaste f\u00f6rmiddagen den m\u00e5naden.<\/p>\n\n\n\n
I dokumentationen fanns en virtualiseringsv\u00e4rd beskriven i detalj: adress, inloggning, hur man ansluter, en fels\u00f6kningsguide f\u00f6r dess lagring.<\/p>\n\n\n\n
Servern var avvecklad. Den hade inte funnits p\u00e5 m\u00e5nader.<\/p>\n\n\n\n
Det l\u00e5ter ofarligt. Det \u00e4r det inte, och sk\u00e4let \u00e4r v\u00e4rt att stanna vid: dokumentation som beskriver n\u00e5got som inte finns \u00e4r s\u00e4mre \u00e4n ingen dokumentation alls.<\/strong> Ingen dokumentation g\u00f6r att man fr\u00e5gar n\u00e5gon. Felaktig dokumentation g\u00f6r att man agerar.<\/p>\n\n\n\n F\u00f6rest\u00e4ll dig den som ska fels\u00f6ka lagring klockan tre p\u00e5 natten, l\u00e4ser den d\u00e4r guiden och b\u00f6rjar leta efter en v\u00e4rd som inte existerar. Nu \u00e4r fels\u00f6kningen tv\u00e5 problem: det ursprungliga, plus f\u00f6rvirringen \u00f6ver varf\u00f6r ingenting st\u00e4mmer.<\/p>\n\n\n\n Det g\u00e4ller i \u00e4nnu h\u00f6gre grad n\u00e4r det \u00e4r en agent som l\u00e4ser. En modell som f\u00e5r dokumentationen som underlag ifr\u00e5gas\u00e4tter inte om servern finns \u2014 den planerar utifr\u00e5n att den g\u00f6r det. F\u00f6r\u00e5ldrad dokumentation blir instruktioner.<\/p>\n\n\n\n Under st\u00e4dningen d\u00f6k en annan sak upp. Backupservern h\u00e4mtar sitt lagringsutrymme fr\u00e5n en n\u00e4tverkslagringsenhet som stod odokumenterad \u2014 den fanns i n\u00e4tet, den hade en adress, och ingenstans stod det vad den gjorde<\/em>.<\/p>\n\n\n\n Allts\u00e5: en enhet som ser ut som n\u00e5got man kan st\u00e4nga av vid st\u00e4dning, men som i praktiken h\u00e5ller hela backupl\u00f6sningen. Den sortens kunskap sitter i en persons huvud tills den dagen personen \u00e4r p\u00e5 semester.<\/p>\n\n\n\n Nu st\u00e5r det i dokumentationen, med versaler: den h\u00e4r f\u00e5r inte st\u00e4ngas av, och det h\u00e4r \u00e4r varf\u00f6r.<\/p>\n\n\n\n Samtidigt kopplades en gammal lagringsenhet bort ur klustret \u2014 kontrollerat, efter att jag verifierat att ingen virtuell disk faktiskt l\u00e5g p\u00e5 den. Skillnaden mellan de tv\u00e5 enheterna var noll ur n\u00e4tverkets perspektiv och total ur verksamhetens.<\/p>\n\n\n\n L\u00e4s dokumentationen som en fr\u00e4mling.<\/strong> Ta en sida i taget och fr\u00e5ga: finns det h\u00e4r fortfarande? Svarar du ”jag tror det” \u00e4r svaret nej tills du kontrollerat.<\/p>\n\n\n\n G\u00e5 \u00e5t andra h\u00e5llet ocks\u00e5.<\/strong> Lista vad som faktiskt svarar i n\u00e4tet och j\u00e4mf\u00f6r mot dokumentationen. Det som finns men inte \u00e4r beskrivet \u00e4r farligare \u00e4n det som \u00e4r beskrivet men inte finns.<\/p>\n\n\n\n Skriv ner vad som inte f\u00e5r r\u00f6ras, och varf\u00f6r.<\/strong> ”F\u00e5r ej st\u00e4ngas av” utan orsak kommer att ignoreras av n\u00e5gon som har br\u00e5ttom. Med orsak \u00f6verlever den.<\/p>\n\n\n\n Dokumentation ruttnar snabbare \u00e4n kod, eftersom ingenting kompilerar den. En felaktig rad i ett program m\u00e4rks; en felaktig rad i en beskrivning ligger kvar och ser lika trov\u00e4rdig ut som resten.<\/p>\n\n\n\n Att stryka \u00e4r d\u00e4rf\u00f6r lika mycket underh\u00e5ll som att skriva. Jag hade lagt tid p\u00e5 att l\u00e4gga till<\/em> beskrivningar i flera \u00e5r utan att en enda g\u00e5ng g\u00e5 igenom och ta bort. Det \u00e4r inte h\u00e5llbart \u2014 och det \u00e4r en syssels\u00e4ttning som l\u00e4mpar sig utm\u00e4rkt f\u00f6r en tr\u00e5kig f\u00f6rmiddag i mars.<\/p>\n\n","protected":false},"excerpt":{"rendered":" En f\u00f6rmiddag med att radera stycken ur dokumentationen. Ingen dokumentation g\u00f6r att man fr\u00e5gar n\u00e5gon \u2014 felaktig dokumentation g\u00f6r att man agerar.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-38","post","type-post","status-publish","format-standard","hentry","category-drift"],"_links":{"self":[{"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/posts\/38","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/comments?post=38"}],"version-history":[{"count":0,"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/posts\/38\/revisions"}],"wp:attachment":[{"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/media?parent=38"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/categories?post=38"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/airex.se\/blogg\/wp-json\/wp\/v2\/tags?post=38"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Det som saknades var farligare<\/h2>\n\n\n\n
S\u00e5 vet du att det funkar<\/h2>\n\n\n\n
Vad jag tar med mig<\/h2>\n\n\n\n