4.6 Vipimo vya nyaraka na maarifa

Muhtasari na msukumo

Mada hii inafunga Sehemu ya 4 kwa kupima kama maarifa yanayohitajika kudumisha msingi wa msimbo kwa usalama yameandikwa na yanapatikana kweli, si tu kama nyaraka zipo mahali fulani kitaalamu. Mada ya 3.5 ilishughulikia mawasiliano na ushirikiano kama wasiwasi wa uzoefu wa msanidi; mada hii inashughulikia suala lilelile la msingi, upatikanaji wa maarifa, kutoka upande wa msimbo: je, mhandisi mpya, au aliyepo anayefanya kazi kwenye msimbo asiojulikana, ana kile anachohitaji kufanya badiliko salama, au maarifa hayo yanaishi tu kwenye vichwa vya idadi inayopungua ya watu wa muda mrefu.

Changamoto ya kipimo hapa ni ngumu kweli, ngumu kuliko vipimo vingi vingine katika kitabu hiki, kwa sababu ubora na manufaa ya nyaraka kwa asili ni ya kibinafsi zaidi kuliko asilimia ya ufunikaji au alama ya ugumu. Mbinu ya mada hii ni kupima wawakilishi wa manufaa badala ya kuwepo: mara ngapi nyaraka zinafikiwa kweli, mara ngapi swali lilelile linaulizwa mara kwa mara licha ya jibu lililoandikwa kuwepo, na inachukua muda gani kwa mtu asiyefahamu mfumo kuwa na tija ndani yake. Hakuna kati ya wawakilishi hawa kinachokamilika peke yake, lakini kwa pamoja vinatoa picha ya uaminifu zaidi sana kuliko kuhesabu idadi ya kurasa za wiki au faili za README ambazo msingi wa msimbo una.

Kwa timu kubwa, wasiwasi wa mada hii unajumlika na kukaa kwa muda mrefu kwa wafanyakazi na watu kuondoka kwa njia ambazo ni rahisi kudharau hadi mgogoro ulazimishe suala: mfumo uliodumishwa kwa miaka na wahandisi wawili walewale unaweza kufanya kazi vizuri kabisa karibu bila nyaraka zilizoandikwa, hadi wote wawili waondoke ndani ya mwaka mmoja, ambapo shirika linagundua maarifa hayakunaswa kamwe mahali popote pa kudumu. Mashirika ya biashara kubwa na ya serikali, yenye muda mrefu zaidi wa maisha ya mifumo na kuendelea kwa wafanyakazi kusiko na uhakika kuliko kampuni changa, yanabeba hatari hii kwa makali zaidi kuliko wengi.

Kanuni kuu

Kuwepo kwa nyaraka si sawa na manufaa ya nyaraka. Pima kama zinasaidia kweli, si tu kama zipo.
Maswali yanayorudiwa licha ya majibu yaliyoandikwa yanafichua tatizo la kupatikana kwa urahisi, si tatizo la juhudi ya nyaraka. Maudhui zaidi si kila mara ndiyo suluhisho.
Muda wa utambulisho hadi mchango wenye tija ni mwakilishi imara, wa vitendo wa afya ya jumla ya maarifa, ukiunganishwa moja kwa moja na vipimo vya ushirikiano vya mada ya 3.5.
Maarifa yanayoishi kwenye vichwa vya watu tu ni hatari ya uimara, si hali thabiti, endelevu, bila kujali yanafanya kazi vizuri jinsi gani sasa.
Nyaraka huoza. Ukurasa uliokuwa sahihi mwaka mmoja uliopita sasa unaweza kupotosha kikamilifu, na uchakavu wenyewe unahitaji kufuatiliwa.

Mapendekezo

Fuatilia ufikiaji wa nyaraka na uchakavu, si kuwepo tu

Pale jukwaa lako la nyaraka linapounga mkono, fuatilia mara ngapi kurasa zinatazamwa kweli, na kando, muda tangu ukurasa ulipasasishwa mara ya mwisho ukilinganishwa na mara ngapi mfumo wa msingi unaoueleza umebadilika (kulinganisha data ya mabadiliko ya mara kwa mara kutoka mada ya 4.3 kuna manufaa ya moja kwa moja hapa). Ukurasa unaoeleza mfumo uliobadilika kwa kiasi kikubwa tangu ukurasa ulipohaririwa mara ya mwisho ni mgombea imara wa kuwa unapotosha kikamilifu badala ya kutosaidia tu, na ishara hii ya uchakavu inastahili umakini angalau kama kufuatilia kama nyaraka zipo kabisa.

Angalia maswali yanayorudiwa kama ishara ya kupatikana kwa urahisi

Ikiwa swali lilelile linaulizwa mara kwa mara kwenye njia ya mazungumzo ya timu au wakati wa utambulisho, licha ya jibu lililoandikwa kuwepo mahali fulani kitaalamu, mfumo huo unafichua tatizo la kupatikana kwa urahisi, jibu halipo mahali watu wanapolitafuta kwa asili, badala ya tatizo la juhudi ya nyaraka ambalo kuandika zaidi kungerekebisha. Fuatilia maswali yanayojirudia waziwazi, na uyatumie kupa kipaumbele kupanga upya au kufanya maudhui yaliyopo yaonekane vizuri zaidi badala ya kuandika zaidi.

Pima muda wa utambulisho hadi mchango wa kwanza wenye maana, wa kujitegemea

Kipimo hiki, kilichotambulishwa katika mada ya 3.5 kama ishara ya ushirikiano, ni vilevile ishara ya nyaraka na afya ya maarifa kutoka upande wa msimbo. Muda mfupi, unaotabirika wa utambulisho unadokeza maarifa yanayopatikana kweli, sahihi; muda mrefu, unaobadilika sana, hasa unaotegemea sana mtu mahususi anayeanza kumtambulisha mwanachama mpya wa timu, unadokeza maarifa yanayoishi yamekusanyika kwa hatari kwenye kumbukumbu ya mtu binafsi badala ya umbo la kudumu, lililoandikwa.

Tambua na upe kipaumbele waziwazi maeneo ya maarifa muhimu yasiyoandikwa

Linganisha data yako ya mkusanyiko wa maarifa (uchambuzi wa kipengele cha basi wa mada ya 3.5) na ufunikaji wa nyaraka: mfumo wenye kipengele cha basi cha moja na hakuna nyaraka zenye maana ni hatari kali, inayojumlika inayostahili umakini wa kipaumbele juu ya mfumo ulioandikwa vizuri wenye kipengele cha basi kidogo kilekile, kwa kuwa nyaraka angalau zinatoa upunguzaji wa sehemu huku mrithi maalum akifunzwa.

Chukulia deni la nyaraka kama kategoria ndani ya mrundikano wako wa deni la kiufundi

Badala ya kufuatilia mapengo ya nyaraka kando na bila rasmi, jumuisha mapengo makubwa ya nyaraka katika mrundikano uleule unaoonekana, uliopimwa ulioelezwa katika mada ya 4.5, hasa kwa mifumo muhimu yenye kipengele cha basi cha chini, ili kazi ya nyaraka ishindane kwa haki kwa uwezo uliopewa kipaumbele badala ya kuahirishwa daima kama kazi ya hadhi ya chini ikilinganishwa na kurekebisha deni linalolenga msimbo.

Mabadilishano: faida na hasara

Mbinu	Faida	Hasara
Hakuna kipimo cha nyaraka	Mzigo mdogo	Hatari ya maarifa inabaki isiyoonekana hadi mgogoro ulazimishe ugunduzi
Kuhesabu kuwepo kwa nyaraka (idadi ya kurasa, uwepo wa README)	Rahisi, rahisi kuripoti	Haisemi chochote kuhusu manufaa, usahihi, au kupatikana kwa urahisi
Kufuatilia ufikiaji na uchakavu	Inafichua manufaa halisi na kuoza	Inahitaji uchanganuzi wa jukwaa la nyaraka na nidhamu ya mapitio endelevu
Muda wa utambulisho kama mwakilishi	Wa vitendo, thabiti, unaounganishwa moja kwa moja na athari halisi ya biashara	Wa kiasili; mambo mengine mbali na nyaraka pia yanaathiri kasi ya utambulisho

Mvutano wa kati ni kupimika dhidi ya maana. Kuwepo kwa nyaraka ni rahisi kabisa kuhesabu na kunakuambia karibu hakuna chenye manufaa; manufaa halisi, kama mtu anaweza kupata na kutegemea maarifa yaliyoandikwa anapoyahitaji, ndicho kinachojali kweli lakini ni kigumu zaidi kupima moja kwa moja. Litatue kwa kutumia wawakilishi ambao mada hii inapendekeza, mifumo ya ufikiaji, uchakavu ukilinganishwa na mabadiliko ya mara kwa mara, maswali yanayorudiwa, na muda wa utambulisho, kwa mchanganyiko, ukikubali kwamba hakuna kimoja kikamilifu lakini kwamba kukutana kwao kuna maana zaidi sana kuliko hesabu ya kuwepo peke yake.

Maswali ya kujadili na timu yako

Kwa mfumo wetu muhimu zaidi, wenye kipengele cha basi cha chini zaidi, je, nyaraka zenye maana, sahihi zipo kweli, au mtaalamu anayeondoka angechukua sehemu kubwa ya maarifa halisi pamoja naye? Hii ndiyo toleo kali zaidi, thabiti zaidi la wasiwasi mkuu wa mada hii; lijibu kwa uaminifu kwa mfumo wenu hatari zaidi mmoja kwanza.
Swali gani linaulizwa mara kwa mara kwenye mazungumzo ya timu yetu licha ya jibu lililoandikwa kuwepo mahali fulani? Mkiweza kulitaja moja mara moja, hilo ni tatizo la kupatikana kwa urahisi linalostahili kurekebishwa moja kwa moja, kwa uwezekano kwa kupanga upya au kufanya maudhui yaliyopo yaonekane vizuri zaidi badala ya kuandika zaidi.
Mwanachama wetu mpya wa karibuni zaidi wa timu alichukua muda gani kufanya mchango wake wa kwanza wenye maana, wa kujitegemea, na ulilinganishwaje na mwanachama wa timu aliyemtangulia? Tofauti kubwa, isiyoelezwa kati ya watu binafsi mara nyingi inaelekeza kwenye maarifa yanayotegemea sana nani anayetambulisha mtu, badala ya nyaraka za kudumu, zinazopatikana.
Lini mwisho tulikagua kama kipande cha nyaraka bado kilikuwa sahihi, ikilinganishwa na jinsi mfumo wa msingi umebadilika tangu kiliandikwa? Jibu la uaminifu likiwa “hatukagui hili kwa utaratibu,” hatari hiyo ya uchakavu huenda ni kubwa kuliko yeyote anavyodhani sasa.
Je, mrundikano wetu wa deni la kiufundi (mada ya 4.5) unajumuisha mapengo ya nyaraka, au kazi ya nyaraka huahirishwa daima kama kazi ya hadhi ya chini ikilinganishwa na marekebisho ya msimbo? Kagua mrundikano wenu halisi na muone kama deni la nyaraka linaonekana na kushindana kwa uwezo uliopewa kipaumbele au halionekani kwa ufanisi.
Ingetugharimu nini ikiwa mtu mmoja au wawili wanaoelewa mfumo wetu muhimu zaidi, wenye nyaraka chache zaidi, waondoke ndani ya mwaka mmoja? Swali hili thabiti, lisilostarehesha linastahili kujibiwa kwa uaminifu badala ya kuchukulia hatari kama ya kufikirika au isiyowezekana.

Mtazamo wa sekta

Kampuni changa. Vipimo rasmi vya nyaraka kwa kawaida si vya lazima na timu ndogo ambapo maarifa yanaenea kupitia mazungumzo ya mara kwa mara, ya moja kwa moja. Hatari ya kuangalia ni mkusanyiko uleule wa kipengele cha basi ambao mada ya 3.5 inaonya dhidi yake, sasa ukitumika mahususi kwa nyaraka: timu inapokua kupita ukubwa ambapo kila mtu anazungumza kila siku, maarifa yasiyoandikwa yaliyofanya kazi vizuri bila rasmi yanakuwa dhima halisi.

Biashara ndogo. Pa kipaumbele kuandika mfumo wako muhimu zaidi, usio na uwiano mdogo zaidi kwanza, hata bila rasmi, badala ya kujaribu nyaraka kamili kuvuka kila kitu. Hati fupi, sahihi inayofunika hatua yako hatari zaidi ya kushindwa ya pekee inatoa thamani halisi zaidi kuliko ufunikaji mpana lakini wa juujuu kila mahali.

Biashara kubwa. Uchakavu wa nyaraka na kupatikana kwa urahisi vyote vinapanuka vibaya hapa, kwa kuwa shirika kubwa linakusanya nyaraka kuvuka timu na majukwaa mengi kwa kasi kuliko yeyote anavyoweza kuziweka za sasa au kupangwa kwa uthabiti. Wekeza katika uchanganuzi wa jukwaa la nyaraka kufuatilia ufikiaji na uchakavu kwa ukubwa, na uchukulie deni la nyaraka kama kategoria ya daraja la kwanza katika mrundikano wako wa deni wa shirika zima.

Serikali. Muda mrefu wa kukaa kwa wafanyakazi wa kawaida katika mashirika ya sekta ya umma unaweza kuficha hatari kali ya maarifa yasiyoandikwa nyuma ya uthabiti dhahiri, kwa kuwa mfumo uliodumishwa na mtu mmoja kwa miaka kumi na mitano unaweza kufanya kazi vizuri kabisa hadi mtu huyo astaafu. Chukulia afya ya nyaraka waziwazi kama suala la mwendelezo wa operesheni, linaloungwa moja kwa moja na upangaji wa wafanyakazi na urithi, si urahisi wa uhandisi tu.

Mifano

Biashara kubwa. Kampuni ya huduma za fedha iligundua, wakati wa upangaji upya usiohusiana, kwamba injini yake kuu ya kukokotoa hatari haikuwa na nyaraka zenye maana zaidi ya maoni machache ya msimbo yaliyopitwa na wakati, na wahandisi wawili waliouelewa vizuri zaidi wote wawili walikuwa wakihamishwa kwenda mpango mpya kwa wakati mmoja. Juhudi ya dharura ya nyaraka, iliyofanywa chini ya shinikizo kubwa la muda, ilitoa na kurekodi maarifa muhimu kabla ya uhamisho kuanza kutumika, lakini mchakato ulichukua wiki kadhaa za muda maalum wa wahandisi wakuu ambao ungeweza kuenezwa polepole zaidi na kwa bei nafuu zaidi ikiwa afya ya nyaraka ingefuatiliwa na kupewa kipaumbele mapema badala ya kugunduliwa kama dharura.

Serikali. Mfumo wa usimamizi wa kesi wa miongo kadhaa wa serikali ya jimbo ulikuwa umekusanya nyaraka nyingi kwa miaka, lakini ukaguzi wa kupatikana kwa urahisi uligundua wanachama wapya wa timu mara kwa mara hawakuweza kupata nyaraka husika zilizopo na waliuliza tena na tena maswali yaleyale machache kwenye njia za timu, maswali ambayo, kwa kweli, tayari yalijibiwa mahali fulani katika jukwaa kubwa, lililopangwa vibaya la nyaraka la wakala. Badala ya kuandika maudhui zaidi, wakala uliwekeza katika kupanga upya na kuboresha muundo wa utafutaji na uongozaji wa nyaraka zake zilizopo, na utafiti wa ufuatiliaji ulionyesha kupungua kunakopimika kwa maswali yanayorudiwa na uzoefu wa utambulisho ulioripotiwa wa kasi zaidi sana kwa wafanyakazi wapya, bila kuongeza ukurasa hata mmoja mpya wa maudhui.

Kesi ya biashara: sababu, ROI, na TCO

Faida ya kupima na kusimamia afya ya nyaraka kwa makusudi ni gharama ya mgogoro iliyoepukwa: mfano wa huduma za fedha hapo juu unaonyesha tofauti kati ya kunasa maarifa kwa mapema, polepole na juhudi ya dharura, iliyobanwa, ya gharama kubwa iliyolazimishwa na uhamisho wa wafanyakazi usiopangwa. Maarifa muhimu yasiyoandikwa ni dhima ya kudumu isiyogharimu chochote kinachoonekana hadi wakati inapokuwa ghali sana mara moja.

Jumla ya gharama ya umiliki kwa kiasi kikubwa ni nidhamu ya kufuatilia wawakilishi ambao mada hii inapendekeza, mifumo ya ufikiaji, uchakavu, maswali yanayorudiwa, muda wa utambulisho, na utayari wa kujumuisha mapengo ya nyaraka kwenye mrundikano uliopewa kipaumbele badala ya kuyachukulia kila wakati kama ya hadhi ya chini kuliko kazi inayolenga msimbo. Nidhamu hiyo inagharimu kidogo zaidi sana kuliko uchimbaji wa maarifa wa hali ya mgogoro ambao mfano wa huduma za fedha unaonyesha kama mbadala.

Mifumo mibaya na mitego

Kuhesabu kuwepo kwa nyaraka badala ya manufaa: kunakuambia karibu hakuna kuhusu kama maarifa yanapatikana kweli yanapohitajika.
Kuandika maudhui zaidi kujibu maswali yanayorudiwa, bila kwanza kukagua kupatikana kwa urahisi: mara nyingi kunashughulikia tatizo lisilo sahihi kabisa.
Kutowahi kukagua uchakavu wa nyaraka ukilinganishwa na jinsi mfumo umebadilika: hatari ya maudhui yanayopotosha kikamilifu, yaliyopitwa na wakati.
Kuchukulia deni la nyaraka kama la hadhi ya chini daima kuliko deni la msimbo: linaliacha lipewe kipaumbele cha chini kwa kudumu na lisilionekana kwenye mrundikano.
Kukosea uthabiti dhahiri, mfumo ambao haujabadilika kwa miaka, kama hatari ndogo: unaweza kuficha tatizo kali la kipengele cha basi kisichoandikwa nyuma ya mfumo ambao bado haujahitaji mtaalamu wake wa pekee.
Kugundua maarifa muhimu yasiyoandikwa tu wakati wa mpito wa dharura wa wafanyakazi: njia ya kushindwa ya gharama kubwa, inayoepukika ambayo mada hii imejengwa kuzuia.

Kielelezo cha ukomavu

Ngazi ya 1, Kuanzisha: Afya ya nyaraka haipimwi; mkusanyiko wa maarifa na hatari ya uchakavu vinagunduliwa tu kupitia mgogoro.
Ngazi ya 2, Kuendeleza: Nyaraka fulani zipo, lakini hakuna ufuatiliaji wa kimfumo wa ufikiaji, uchakavu, au kupatikana kwa urahisi.
Ngazi ya 3, Kusawazisha: Ufikiaji na uchakavu vinafuatiliwa kwa mifumo muhimu, na muda wa utambulisho unapimwa kama mwakilishi wa afya ya maarifa shirika zima.
Ngazi ya 4, Kusimamia: Mapengo ya nyaraka yanajumuishwa kwenye mrundikano uliopewa kipaumbele wa deni la kiufundi, yakilinganishwa na hatari ya kipengele cha basi kutambua hatari kali zaidi za pamoja.
Ngazi ya 5, Kuratibu: Shirika linatambua na kushughulikia mapema hatari ya maarifa muhimu yasiyoandikwa kabla mpito wa wafanyakazi haujalazimisha suala, na linaweza kuonyesha uboreshaji mahususi, unaopimika wa utambulisho au mwitikio wa tukio uliofuatiliwa hadi uwekezaji wa nyaraka.

Mawazo ya kujadili

Mchanganyiko wetu mmoja mkali zaidi wa kipengele cha basi cha chini na nyaraka duni sasa hivi ni upi?
Swali gani linaulizwa mara kwa mara licha ya jibu lililoandikwa kuwepo?
Tungejuaje kama kipande cha nyaraka muhimu kimekuwa kimechakaa na cha kupotosha?
Je, mrundikano wetu wa deni la kiufundi unajumuisha mapengo ya nyaraka, au hayaonekani?
Ingetugharimu nini mtaalamu wa pekee wa mfumo wetu wenye nyaraka duni zaidi aondoke mwaka huu?

Mambo muhimu ya kukumbuka

Pima manufaa, si kuwepo: kama nyaraka zinasaidia kweli, kwa kutumia wawakilishi kama mifumo ya ufikiaji, uchakavu, na maswali yanayorudiwa.
Maswali yanayorudiwa licha ya majibu yaliyoandikwa yanafichua tatizo la kupatikana kwa urahisi, si lazima tatizo la juhudi ya maudhui.
Muda wa utambulisho hadi mchango wenye tija ni mwakilishi imara, wa vitendo wa afya ya jumla ya maarifa.
Maarifa muhimu yasiyoandikwa ni hatari inayojumlika, hasa yakichanganywa na kipengele cha basi cha chini (mada ya 3.5); haigharimu chochote kinachoonekana hadi inagharimu sana mara moja.
Jumuisha mapengo ya nyaraka kwenye mrundikano wako wa deni la kiufundi (mada ya 4.5) ili yashindane kwa haki kwa uwezo uliopewa kipaumbele.

Marejeo na usomaji zaidi

Docs for Developers: An Engineer’s Field Guide to Technical Writing, na Jared Bhatti, Zachariah Goldberg, Ted Kubaska, na Sarah Moir (mazoea ya vitendo ya nyaraka kwa timu za uhandisi).
A Philosophy of Software Design, na John Ousterhout (uhusiano kati ya nyaraka, ugumu, na uwezo wa kudumisha).
Team Topologies, na Matthew Skelton na Manuel Pais (athari za usanifu wa kishirika za maarifa yaliyokusanyika dhidi ya yaliyosambazwa).
Accelerate: The Science of Lean Software and DevOps, na Nicole Forsgren, Jez Humble, na Gene Kim (nyaraka kama mojawapo ya uwezo unaohusiana na utendaji wa utoaji).