4.6 Skjölunar- og þekkingarmælikvarðar

Yfirlit og tilgangur

Þetta viðfangsefni lokar 4. hluta með því að mæla hvort þekkingin sem þarf til að viðhalda kóðagrunni örugglega sé í raun skjalfest og finnanleg, ekki bara hvort skjölun sé tæknilega til einhvers staðar. Viðfangsefni 3.5 fjallaði um samskipti og samvinnu sem þróunarupplifunaráhyggju; þetta viðfangsefni fjallar um sama undirliggjandi mál, tiltækileika þekkingar, frá hlið kóðans: hefur nýr verkfræðingur, eða núverandi sem vinnur í ókunnum kóða, það sem hann þarf til að gera örugga breytingu, eða býr sú þekking aðeins í höfðum minnkandi fjölda reyndra starfsmanna.

Mælingaráskorunin hér er sannarlega erfið, erfiðari en flestir aðrir mælikvarðar í þessari bók, því skjölunargæði og notagildi eru í eðli sínu huglægari en þekjuhundraðshlutfall eða flækjustigseinkunn. Nálgun þessa viðfangsefnis er að mæla staðgengla notagildis frekar en tilvistar: hve oft skjölun er í raun opnuð, hve oft sama spurning er spurð endurtekið þrátt fyrir að skjalfest svar sé til, og hve langan tíma það tekur einhvern ókunnugan kerfi að verða afkastamikill í því. Enginn þessara staðgengla er fullkominn einn og sér, en saman gefa þeir langtum heiðarlegri mynd en að telja fjölda wiki-síðna eða README-skráa sem kóðagrunnur inniheldur.

Fyrir stór teymi magnast áhyggjur þessa viðfangsefnis með starfsaldri og starfsmannaveltu skipulagsheildar á vegu sem auðvelt er að vanmeta þar til kreppa þvingar málið: kerfi sem sömu tveir verkfræðingar hafa viðhaldið árum saman getur virkað fullkomlega vel með nær enga skriflega skjölun, allt þar til báðir þessir verkfræðingar hætta innan sama árs, en þá uppgötvar skipulagsheildin að þekkingin var aldrei raunverulega fönguð neins staðar varanlega. Stórfyrirtæki og hið opinbera, með yfirleitt lengri kerfislíftíma og óvissari samfellu starfsfólks en sprotafyrirtæki, bera þessa áhættu bráðar en flestir.

Lykilmeginreglur

Tilvist skjölunar er ekki það sama og notagildi skjölunar. Mældu hvort hún hjálpar í raun, ekki bara hvort hún er til staðar.
Endurteknar spurningar þrátt fyrir skjalfest svör afhjúpa auðfinnanleikavanda, ekki skjölunarfyrirhafnarvanda. Meira efni er ekki alltaf lagfæringin.
Þjálfunartími að afkastamiklu framlagi er sterk, hagnýt vísbending um heildarþekkingarheilsu, sem tengist beint samvinnumælikvörðum viðfangsefnis 3.5.
Þekking sem býr aðeins í höfðum fólks er endingaráhætta, ekki stöðugt, sjálfbært ástand, hversu vel sem hún virkar núna.
Skjölun rýrnar. Síða sem var nákvæm fyrir ári kann nú að vera virkt villandi, og úreldingu sjálfa þarf að rekja.

Ráðleggingar

Raktu aðgang að skjölun og úreldingu hennar, ekki bara tilvist

Þar sem skjölunarvettvangur þinn styður það, raktu hve oft síður eru í raun skoðaðar, og sérstaklega hve langt er síðan síða var síðast uppfærð miðað við hve oft undirliggjandi kerfið sem hún lýsir hefur breyst (að víxlvísa veltugögn úr viðfangsefni 4.3 er beint gagnlegt hér). Síða sem lýsir kerfi sem hefur breyst verulega síðan hún var síðast breytt er sterkur frambjóðandi til að vera virkt villandi frekar en bara gagnslaus, og þetta úreldismerki verðskuldar að minnsta kosti jafn mikla athygli og að rekja hvort skjölun sé til yfirleitt.

Gættu að endurteknum spurningum sem auðfinnanleikamerki

Ef sama spurning er spurð endurtekið í teymisspjallrás eða við þjálfun, þrátt fyrir að skjalfest svar sé tæknilega til einhvers staðar, afhjúpar það mynstur auðfinnanleikavanda, svarið er ekki þar sem fólk leitar eðlilega að því, frekar en skjölunarfyrirhafnarvanda sem meiri skrif myndu laga. Raktu endurteknar spurningar skýrt, og notaðu þær til að forgangsraða að endurskipuleggja eða draga betur fram fyrirliggjandi efni frekar en að skrifa meira af því.

Mældu þjálfunartíma að fyrsta marktæka, sjálfstæða framlagi

Þessi mælikvarði, kynntur í viðfangsefni 3.5 sem samvinnumerki, er jafnt skjölunar- og þekkingarheilsumerki frá hlið kóðans. Stöðugt stuttur, fyrirsjáanlegur þjálfunartími bendir til sannarlega aðgengilegrar, nákvæmrar þekkingar; langur, mjög breytilegur tími, einkum sá sem veltur mikið á því hvaða tiltekna manneskja þjálfar nýjan liðsmann, bendir til þekkingar sem býr hættulega einbeitt í minni einstaklinga frekar en varanlegu, skriflegu formi.

Greindu og forgangsraðaðu óskjalfestum mikilvægum þekkingarsvæðum skýrt

Víxlvísaðu þekkingareinbeitingargögnum þínum (rútuþáttargreining viðfangsefnis 3.5) við skjölunarþekju: kerfi með rútuþátt upp á einn og enga marktæka skjölun er alvarleg, magnandi áhætta sem verðskuldar forgangsathygli umfram vel skjalfest kerfi með sama lága rútuþátt, því skjölunin veitir að minnsta kosti hlutaúrlausn meðan sérstakur arftaki er þjálfaður.

Meðhöndlaðu skjölunarskuld sem flokk innan tæknilega skuldabiðlistans þíns

Frekar en að rekja skjölunarbil sérstaklega og óformlega, felldu veruleg skjölunarbil inn í sama sýnilega, magnbundna biðlistann sem lýst er í viðfangsefni 4.5, einkum fyrir mikilvæg, lágan-rútuþátts kerfi, svo skjölunarvinna keppi sanngjarnt um forgangsraðaða getu í stað þess að vera stöðugt frestað sem lægra metið verkefni samanborið við kóðamiðaðar skuldarúrbætur.

Málamiðlanir: kostir og gallar

Nálgun	Kostir	Gallar
Engin skjölunarmæling	Lítil yfirbygging	Þekkingaráhætta helst ósýnileg þar til kreppa þvingar uppgötvun
Að telja tilvist skjölunar (síðufjöldi, README-nærvera)	Einfalt, auðvelt að skýra frá	Segir ekkert um notagildi, nákvæmni eða auðfinnanleika
Rakning aðgangs og úreldingar	Afhjúpar raunverulegt notagildi og rýrnun	Krefst greininga skjölunarvettvangs og áframhaldandi yfirferðaraga
Þjálfunartími sem staðgengill	Hagnýtur, áþreifanlegur, tengist beint raunverulegum viðskiptaáhrifum	Óbeinn; aðrir þættir en skjölun hafa líka áhrif á þjálfunarhraða

Aðalspennan er mælanleiki á móti merkingu. Tilvist skjölunar er léttvægt auðvelt að telja og segir þér næstum ekkert gagnlegt; sannarlegt notagildi, hvort einhver geti í raun fundið og reitt sig á skjalfesta þekkingu þegar hann þarf hana, er það sem skiptir í raun máli en er erfiðara að mæla beint. Leystu spennuna með því að nota staðgenglana sem þetta viðfangsefni mælir með, aðgangsmynstur, úreldingu miðað við veltu, endurteknar spurningar og þjálfunartíma, saman, og samþykkja að enginn einn sé fullkominn en að samleitni þeirra sé langtum marktækari en tilvistartalning ein.

Spurningar til að ræða með teyminu

Fyrir mikilvægasta, lægsta-rútuþáttar kerfi okkar, er marktæk, nákvæm skjölun í raun til, eða myndi brottfarandi sérfræðingur taka mest af raunverulegri þekkingu með sér? Þetta er skarpasta, áþreifanlegasta útgáfa megináhyggju þessa viðfangsefnis; svarið heiðarlega fyrst fyrir áhættumesta stakt kerfi ykkar.
Hvaða spurning er spurð endurtekið í teymisspjalli okkar þrátt fyrir að skjalfest svar sé til einhvers staðar? Ef þið getið nefnt eina strax, er það auðfinnanleikavandi sem vert er að laga beint, líklega með því að endurskipuleggja eða draga betur fram fyrirliggjandi efni frekar en að skrifa meira.
Hve langan tíma tók nýjasti nýi liðsmaður okkar að leggja fram sitt fyrsta marktæka, sjálfstæða framlag, og hvernig bar það sig saman við liðsmanninn á undan honum? Stór, óútskýrður breytileiki milli einstaklinga bendir oft til þekkingar sem veltur mikið á því hver þjálfar einhvern, frekar en varanlegrar, aðgengilegrar skjölunar.
Hvenær athuguðum við síðast hvort skjölun væri enn nákvæm, miðað við hve mikið undirliggjandi kerfið hefur breyst síðan hún var skrifuð? Ef heiðarlega svarið er „við athugum þetta ekki kerfisbundið“ er sú úreldingaráhætta líklega stærri en nokkur gerir ráð fyrir núna.
Inniheldur tæknilegi skuldabiðlisti okkar (viðfangsefni 4.5) skjölunarbil, eða er skjölunarvinnu stöðugt frestað sem lægra metnu verkefni samanborið við kóðalagfæringar? Athugið raunverulegan biðlista ykkar og sjáið hvort skjölunarskuld er sýnileg og keppir um forgangsraðaða getu eða er í reynd ósýnileg.
Hvað myndi það kosta okkur ef einn eða tveir einstaklingar sem skilja mikilvægasta, minnst skjalfesta kerfi okkar hættu innan sama árs? Þessa áþreifanlegu, óþægilegu spurningu er vert að svara heiðarlega frekar en að meðhöndla áhættuna sem óhlutstæða eða ólíklega.

Geirasjónarhorn

Sprotafyrirtæki. Formlegir skjölunarmælikvarðar eru yfirleitt óþarfir með lítið teymi þar sem þekking dreifist gegnum stöðug, bein samtöl. Áhættan sem vert er að fylgjast með er sama rútuþáttareinbeiting og viðfangsefni 3.5 varar við, nú beitt sérstaklega á skjölun: þegar teymið vex umfram stærðina þar sem allir tala saman daglega verður óskjalfest þekking, sem virkaði vel óformlega, raunveruleg skuldbinding.

Lítil fyrirtæki. Forgangsraðaðu að skjalfesta mikilvægasta, minnst-afritaða kerfið þitt fyrst, jafnvel óformlega, frekar en að reyna yfirgripsmikla skjölun yfir allt. Stutt, nákvæmt skjal sem nær yfir áhættumesta stakan bilunarpunkt þinn skilar meira raunverulegu virði en víð en grunn þekja alls staðar.

Stórfyrirtæki. Skjölunarúrelding og auðfinnanleiki stækka báðar illa hér, því stór skipulagsheild safnar skjölun yfir mörg teymi og vettvanga hraðar en nokkur getur haldið henni nýrri eða samræmt skipulagðri. Fjárfestu í greiningum skjölunarvettvangs til að rekja aðgang og úreldingu í stórum mæli, og meðhöndlaðu skjölunarskuld sem fyrsta flokks flokk í skipulagsheildarvíðum skuldabiðlista þínum.

Hið opinbera. Langur starfsaldur algengur í opinberum skipulagsheildum getur falið alvarlega óskjalfesta-þekkingaráhættu á bak við sýnilegan stöðugleika, því kerfi sem sama manneskjan hefur viðhaldið í fimmtán ár getur virkað fullkomlega vel allt þar til sú manneskja lætur af störfum. Meðhöndlaðu skjölunarheilsu skýrt sem samfellu-rekstrar áhyggjuefni, tengt beint við mönnunar- og arftakaáætlun, ekki bara verkfræðilegan fínleika.

Dæmi

Stórfyrirtæki. Fjármálaþjónustufyrirtæki uppgötvaði, við ótengda endurskipulagningu, að kjarnaáhættureikningsvél þess hafði enga marktæka skjölun umfram nokkrar úreltar kóðaathugasemdir, og verkfræðingarnir tveir sem skildu hana best voru báðir endurúthlutaðir í nýtt framtak samtímis. Neyðarskjölunarátak, framkvæmt undir verulegri tímapressu, dró fram og skráði mikilvægu þekkinguna áður en endurúthlutunin tók gildi, en ferlið tók nokkrar vikur af sérstökum tíma æðri verkfræðinga sem hefði mátt dreifa hægfara og ódýrar ef skjölunarheilsa hefði verið rakin og forgangsraðað fyrirbyggjandi frekar en uppgötvuð sem neyðartilvik.

Hið opinbera. Áratugagamalt málastjórnunarkerfi ríkisstjórnar hafði safnað umtalsverðri skjölun yfir árin, en auðfinnanleikaúttekt fann að nýir liðsmenn gátu stöðugt ekki fundið viðeigandi fyrirliggjandi skjölun og spurðu endurtekið sömu fáu spurninganna í teymisrásum, spurninga sem voru í raun þegar svarað einhvers staðar í víðfeðmum, illa skipulögðum skjölunarvettvangi stofnunarinnar. Frekar en að skrifa meira efni fjárfesti stofnunin í að endurskipuleggja og bæta leitar- og leiðsagnarbyggingu fyrirliggjandi skjölunar sinnar, og eftirfylgnikönnun sýndi mælanlega minnkun endurtekinna spurninga og marktækt hraðari tilkynnta þjálfunarupplifun nýs starfsfólks, án þess að bæta við einni einustu nýrri efnissíðu.

Viðskiptarök: hvatar, ávöxtun fjárfestingar og heildareignarkostnaður

Ávöxtun af því að mæla og stýra skjölunarheilsu vísvitandi er forðaður kreppukostnaður: fjármálaþjónustudæmið hér að ofan sýnir muninn á fyrirbyggjandi, hægfara þekkingarfangi og dýru, þjöppuðu neyðarátaki sem óskipulögð starfsmannahreyfing þvingar fram. Óskjalfest mikilvæg þekking er viðvarandi skuldbinding sem kostar ekkert sýnilega þar til augnablikið sem hún verður mjög dýr í einu lagi.

Heildareignarkostnaður er aðallega agi þess að rekja staðgenglana sem þetta viðfangsefni mælir með, aðgangsmynstur, úreldingu, endurteknar spurningar, þjálfunartíma, og viljinn til að fella skjölunarbil inn í forgangsraðaðan biðlista frekar en að meðhöndla þau sem stöðugt lægra metin en kóðamiðuð vinna. Sá agi kostar langtum minna en kreppuhams-þekkingarútdrátturinn sem fjármálaþjónustudæmið sýnir sem valkostinn.

Andmynstur og gildrur

Að telja tilvist skjölunar frekar en notagildi: segir þér næstum ekkert um hvort þekking er í raun aðgengileg þegar hún er nauðsynleg.
Að skrifa meira efni sem viðbragð við endurteknum spurningum, án þess að athuga auðfinnanleika fyrst: tekur oft á röngu vandamáli alveg.
Að athuga aldrei skjölunarúreldingu miðað við hve mikið kerfið hefur breyst: á hættu á virkt villandi, úrelt efni.
Að meðhöndla skjölunarskuld sem stöðugt lægra metna en kóðaskuld: skilur hana eftir langvarandi aftarlega-í-forgangsröð og ósýnilega á biðlistanum.
Að rugla sýnilegum stöðugleika, kerfi sem hefur ekki breyst árum saman, við litla áhættu: getur falið alvarlegan, óskjalfestan rútuþáttarvanda á bak við kerfi sem hefur einfaldlega ekki þurft eina sérfræðing sinn enn.
Að uppgötva mikilvæga óskjalfesta þekkingu aðeins við neyðarstarfsmannaskipti: dýri, forðanlegi bilunarmátinn sem þetta viðfangsefni er byggt til að koma í veg fyrir.

Þroskalíkan

Stig 1, Upphaf: Skjölunarheilsa er ekki mæld; þekkingareinbeiting og úreldingaráhætta uppgötvast aðeins gegnum kreppu.
Stig 2, Þróun: Einhver skjölun er til, en engin kerfisbundin rakning aðgangs, úreldingar eða auðfinnanleika.
Stig 3, Stöðlun: Aðgangur og úrelding eru rakin fyrir mikilvæg kerfi, og þjálfunartími er mældur sem staðgengill þekkingarheilsu í allri skipulagsheildinni.
Stig 4, Stjórnun: Skjölunarbil eru felld inn í forgangsraðaða tæknilega skuldabiðlistann, víxlvísuð við rútuþáttaáhættu til að greina alvarlegustu samanlögðu áhætturnar.
Stig 5, Samhæfing: Skipulagsheildin greinir og tekst á við óskjalfesta mikilvæga þekkingaráhættu fyrirbyggjandi áður en mönnunarskipti þvinga málið, og getur bent á tilteknar, mælanlegar þjálfunar- eða atvikaviðbragðsbætur raktar til skjölunarfjárfestingar.

Hugmyndir til umræðu

Hver er alvarlegasta samsetning lágs rútuþáttar og lélegrar skjölunar hjá okkur núna?
Hvaða spurning er spurð endurtekið þrátt fyrir að skjalfest svar sé til?
Hvernig myndum við vita ef mikilvæg skjölun hefði orðið úrelt og villandi?
Inniheldur tæknilegi skuldabiðlisti okkar skjölunarbil, eða eru þau ósýnileg?
Hvað myndi það kosta okkur ef eini sérfræðingur minnst skjalfesta kerfis okkar hætti á þessu ári?

Helstu atriði til að muna

Mældu notagildi, ekki tilvist: hvort skjölun hjálpar í raun, með staðgenglum eins og aðgangsmynstrum, úreldingu og endurteknum spurningum.
Endurteknar spurningar þrátt fyrir skjalfest svör afhjúpa auðfinnanleikavanda, ekki endilega efnisfyrirhafnarvanda.
Þjálfunartími að afkastamiklu framlagi er sterk, hagnýt vísbending um heildarþekkingarheilsu.
Óskjalfest mikilvæg þekking er magnandi áhætta, einkum ásamt lágum rútuþætti (viðfangsefni 3.5); hún kostar ekkert sýnilega þar til hún kostar mikið í einu lagi.
Felldu skjölunarbil inn í tæknilega skuldabiðlista þinn (viðfangsefni 4.5) svo þau keppi sanngjarnt um forgangsraðaða getu.

Heimildir og frekara lesefni

Docs for Developers: An Engineer’s Field Guide to Technical Writing, eftir Jared Bhatti, Zachariah Goldberg, Ted Kubaska og Sarah Moir (hagnýtar skjölunarvenjur fyrir verkfræðiteymi).
A Philosophy of Software Design, eftir John Ousterhout (sambandið milli skjölunar, flækjustigs og viðhaldshæfni).
Team Topologies, eftir Matthew Skelton og Manuel Pais (skipulagshönnunaráhrif einbeittrar á móti dreifðrar þekkingar).
Accelerate: The Science of Lean Software and DevOps, eftir Nicole Forsgren, Jez Humble og Gene Kim (skjölun sem ein af getunum sem fylgja afhendingarframmistöðu).