4.6 Metrigau dogfennaeth a gwybodaeth

Trosolwg a chymhelliant

Mae’r pwnc hwn yn cau Rhan 4 trwy fesur a yw’r wybodaeth sydd ei angen i gynnal sylfaen cod yn ddiogel mewn gwirionedd wedi’i dogfennu ac y gellir dod o hyd iddi, nid dim ond a yw dogfennaeth yn bodoli’n dechnegol yn rhywle. Roedd pwnc 3.5’n ymdrin â chyfathrebu a chydweithio fel pryder profiad-datblygwyr; mae’r pwnc hwn yn ymdrin â’r un mater sylfaenol, argaeledd gwybodaeth, o ochr y cod: a oes gan beiriannydd newydd, neu un presennol sy’n gweithio ar god anghyfarwydd, yr hyn sydd ei angen arno i wneud newid diogel, neu a yw’r wybodaeth honno’n byw dim ond ym mhennaethiaid nifer sy’n crebachu o bobl hirsefydlog.

Mae her fesur yma’n wirioneddol anodd, yn anos na’r rhan fwyaf o fetrigau eraill yn y llyfr hwn, oherwydd bod ansawdd a defnyddioldeb dogfennaeth yn gynhenid fwy goddrychol na chanran gorchudd neu sgôr cymhlethdod. Dull y pwnc hwn yw mesur dirprwyon ar gyfer defnyddioldeb yn hytrach na bodolaeth: pa mor aml y mae dogfennaeth mewn gwirionedd yn cael ei chyrchu, pa mor aml y gofynnir yr un cwestiwn drosodd a throsodd er gwaethaf bod ateb dogfennedig yn bodoli, a pha mor hir y mae’n ei gymryd i rywun anghyfarwydd â system ddod yn gynhyrchiol ynddi. Nid oes yr un o’r dirprwyon hyn yn berffaith ar ei ben ei hun, ond gyda’i gilydd maent yn rhoi darlun llawer mwy onest na chyfrif nifer y tudalennau wici neu ffeiliau README y mae sylfaen cod yn eu cynnwys.

I dimau mawr, mae pryderon y pwnc hwn yn cyfansymio â deiliadaeth a throsiant sefydliadol mewn ffyrdd sy’n hawdd eu tanamcangyfrif tan i argyfwng orfodi’r mater: gall system a gynhelir am flynyddoedd gan yr un ddau beiriannydd weithredu’n berffaith iawn gyda bron dim dogfennaeth ysgrifenedig, hyd nes i’r ddau beiriannydd hynny adael o fewn yr un flwyddyn, ar y pwynt hwnnw mae’r sefydliad yn darganfod na chafodd y wybodaeth ei chapio erioed unrhyw le parhaol. Mae sefydliadau menter a llywodraeth, â hydoedd system fel arfer yn hirach a pharhad staff yn llai sicr na chwmni newydd, yn cario’r risg hon yn fwy dwys na’r rhan fwyaf.

Egwyddorion allweddol

Nid yw bodolaeth dogfennaeth yr un peth â defnyddioldeb dogfennaeth. Mesurwch a yw’n helpu mewn gwirionedd, nid dim ond a yw’n bresennol.
Mae cwestiynau ailadroddus er gwaethaf atebion dogfennedig yn datgelu problem darganfyddadwyedd, nid problem ymdrech- ddogfennaeth. Nid mwy o gynnwys yw’r ateb bob amser.
Mae amser cynefino i gyfraniad cynhyrchiol yn ddirprwy cryf, ymarferol ar gyfer iechyd gwybodaeth cyffredinol, gan gysylltu’n uniongyrchol â metrigau cydweithio pwnc 3.5.
Mae gwybodaeth sy’n byw dim ond ym mhennaethiaid pobl yn risg parhad, nid cyflwr sefydlog, cynaliadwy, waeth pa mor dda y mae’n gweithredu ar hyn o bryd.
Mae dogfennaeth yn dadfeilio. Gall tudalen a oedd yn gywir flwyddyn yn ôl fod yn gamarweiniol yn weithredol nawr, ac mae angen olrhain hynafedd ei hun.

Argymhellion

Olrheiniwch fynediad a hynafedd dogfennaeth, nid dim ond bodolaeth

Lle mae eich platfform dogfennaeth yn ei gefnogi, olrheiniwch pa mor aml y gwelir tudalennau mewn gwirionedd, ac ar wahân, pa mor hir ers y diweddarwyd tudalen ddiwethaf mewn perthynas â pha mor aml y mae’r system sylfaenol y mae’n ei disgrifio wedi newid (mae croesgyfeirio data trosiant o bwnc 4.3’n uniongyrchol ddefnyddiol yma). Mae tudalen sy’n disgrifio system sydd wedi newid yn sylweddol ers i’r dudalen gael ei golygu ddiwethaf yn ymgeisydd cryf ar gyfer bod yn gamarweiniol yn weithredol yn hytrach nag yn ddim ond ddiddefnydd, ac mae’r signal hynafedd hwn yn haeddu o leiaf cymaint o sylw ag olrhain a yw dogfennaeth yn bodoli o gwbl.

Gwyliwch am gwestiynau ailadroddus fel signal darganfyddadwyedd

Os gofynnir yr un cwestiwn drosodd a throsodd mewn sianel sgwrsio tîm neu yn ystod cynefino, er gwaethaf bod ateb dogfennedig yn bodoli’n dechnegol yn rhywle, mae’r patrwm hwnnw’n datgelu problem darganfyddadwyedd, nid yw’r ateb lle mae pobl yn edrych amdano’n naturiol, yn hytrach na phroblem ymdrech-ddogfennaeth y byddai mwy o ysgrifennu’n ei thrwsio. Olrheiniwch gwestiynau ailadroddus yn benodol, a’u defnyddio i flaenoriaethu ail-drefnu neu ddatgelu cynnwys presennol yn well dros ysgrifennu mwy ohono.

Mesurwch amser cynefino i gyfraniad ystyrlon, annibynnol cyntaf

Mae’r metrig hwn, a gyflwynwyd ym mhwnc 3.5 fel signal cydweithio, hefyd yn signal dogfennaeth ac iechyd-gwybodaeth o ochr y cod. Mae amser cynefino byr, rhagweladwy’n gyson yn awgrymu gwybodaeth wirioneddol hygyrch, gywir; mae amser hir, hynod amrywiol, yn enwedig un sy’n dibynnu’n drwm ar ba berson penodol sy’n digwydd cynefino aelod tîm newydd, yn awgrymu gwybodaeth sy’n byw wedi’i chrynhoi’n beryglus mewn cof unigol yn hytrach na ffurf ysgrifenedig, barhaol.

Nodwch a blaenoriaethwch ardaloedd gwybodaeth-dyngedfennol heb eu dogfennu’n benodol

Croesgyfeiriwch eich data crynhoad-gwybodaeth (dadansoddiad ffactor-bws pwnc 3.5) â gorchudd dogfennaeth: mae system â ffactor bws o un a dim dogfennaeth ystyrlon yn risg ddifrifol, cyfansymio sy’n haeddu sylw blaenoriaeth dros system â dogfennaeth dda â’r un ffactor bws isel, gan fod y ddogfennaeth o leiaf yn darparu lliniaru rhannol tra bo olynydd pwrpasol yn cael ei hyfforddi.

Triniwch ddyled dogfennaeth fel categori o fewn eich cronfa-waith dyled dechnegol

Yn hytrach nag olrhain bylchau dogfennaeth ar wahân ac yn anffurfiol, plygwch fylchau dogfennaeth sylweddol i mewn i’r un gronfa-waith weladwy, wedi’i meintioli a ddisgrifir ym mhwnc 4.5, yn enwedig ar gyfer systemau dyngedfennol, ffactor-bws-isel, fel bod gwaith dogfennaeth yn cystadlu’n deg am gynhwysedd wedi’i flaenoriaethu yn hytrach na chael ei ohirio’n barhaus fel tasg statws-is o’i gymharu ag unioni dyled sy’n canolbwyntio ar god.

Cyfnewidiadau: manteision ac anfanteision

Dull	Manteision	Anfanteision
Dim mesuriad dogfennaeth	Baich isel	Mae risg gwybodaeth yn aros yn anweledig tan i argyfwng orfodi darganfyddiad
Cyfrif bodolaeth dogfennaeth (cyfrif tudalen, presenoldeb README)	Syml, hawdd ei adrodd	Yn dweud dim am ddefnyddioldeb, cywirdeb, na darganfyddadwyedd
Olrhain mynediad a hynafedd	Yn datgelu defnyddioldeb a dadfeiliad gwirioneddol	Angen dadansoddeg platfform-dogfennaeth a disgyblaeth adolygu barhaus
Amser cynefino fel dirprwy	Ymarferol, concrid, yn clymu’n uniongyrchol wrth effaith busnes wirioneddol	Anuniongyrchol; mae ffactorau eraill heblaw dogfennaeth hefyd yn effeithio ar gyflymder cynefino

Y tensiwn canolog yw mesuradwyedd yn erbyn ystyr. Mae bodolaeth dogfennaeth yn ddibwys hawdd ei chyfrif ac yn dweud bron dim byd defnyddiol wrthych; defnyddioldeb gwirioneddol, a all rywun ddod o hyd i wybodaeth ddogfennedig a dibynnu arni pan fydd ei hangen arno, yw’r hyn sy’n wirioneddol bwysig ond mae’n anos ei fesur yn uniongyrchol. Datryswch y tensiwn trwy ddefnyddio’r dirprwyon y mae’r pwnc hwn yn eu hargymell, patrymau mynediad, hynafedd mewn perthynas â throsiant, cwestiynau ailadroddus, ac amser cynefino, ar y cyd, gan dderbyn nad yw’r un ohonynt yn berffaith ond bod eu cydgyfeiriant yn llawer mwy ystyrlon na chyfrif bodolaeth yn unig.

Cwestiynau i’w trafod gyda’ch tîm

Ar gyfer ein system fwyaf dyngedfennol, ffactor-bws-isaf, a yw dogfennaeth ystyrlon, gywir mewn gwirionedd yn bodoli, neu a fyddai arbenigwr sy’n gadael yn mynd â’r rhan fwyaf o’r wybodaeth wirioneddol gyda nhw? Dyma’r fersiwn cliriaf, mwyaf concrid o bryder canolog y pwnc hwn; atebwch ef yn onest ar gyfer eich system risg-uchaf sengl yn gyntaf.
Pa gwestiwn a ofynnir drosodd a throsodd yn ein sgwrs tîm er gwaethaf bod ateb dogfennedig yn bodoli yn rhywle? Os gallwch enwi un ar unwaith, mae hynny’n broblem darganfyddadwyedd sy’n werth ei thrwsio’n uniongyrchol, yn debygol trwy ail-drefnu neu ddatgelu cynnwys presennol yn well yn hytrach nag ysgrifennu mwy.
Pa mor hir y cymerodd ein haelod tîm newydd mwyaf diweddar i wneud ei gyfraniad ystyrlon, annibynnol cyntaf, a sut roedd hynny’n cymharu â’r aelod tîm o’u blaenau? Mae amrywiant mawr, heb ei egluro rhwng unigolion yn aml yn pwyntio at wybodaeth sy’n dibynnu’n drwm ar bwy sy’n digwydd cynefino rhywun, yn hytrach na dogfennaeth barhaol, hygyrch.
Pryd wnaethom wirio ddiwethaf a oedd darn o ddogfennaeth yn dal yn gywir, mewn perthynas â faint mae’r system sylfaenol wedi newid ers iddi gael ei hysgrifennu? Os yw’r ateb onest yn “nid ydym yn gwirio hyn yn systematig,” mae’r risg hynafedd hwnnw’n debygol yn fwy nag y mae unrhyw un yn ei dybio ar hyn o bryd.
A yw ein cronfa-waith dyled dechnegol (pwnc 4.5) yn cynnwys bylchau dogfennaeth, neu a yw gwaith dogfennaeth yn cael ei ohirio’n barhaus fel tasg statws-is o’i gymharu â thrwsiadau cod? Gwiriwch eich cronfa-waith wirioneddol a gwelwch a yw dyled dogfennaeth yn weladwy ac yn cystadlu am gynhwysedd wedi’i flaenoriaethu neu’n effeithiol anweledig.
Beth fyddai’n ei gostio i ni petai’r un neu ddau berson sy’n deall ein system fwyaf dyngedfennol, leiaf ei dogfennu’n gadael o fewn yr un flwyddyn? Mae’r cwestiwn concrid, anghyfforddus hwn yn werth ei ateb yn onest yn hytrach na thrin y risg fel un haniaethol neu annhebygol.

Golwg sector

Cwmni newydd. Mae metrigau dogfennaeth ffurfiol fel arfer yn ddiangen gyda thîm bach lle mae gwybodaeth yn lledaenu trwy sgwrs gyson, uniongyrchol. Y risg i’w wylio yw’r un crynhoad ffactor-bws y mae pwnc 3.5 yn rhybuddio yn ei erbyn, wedi’i gymhwyso’n benodol i ddogfennaeth nawr: wrth i’r tîm dyfu heibio’r maint lle mae pawb yn siarad bob dydd, mae gwybodaeth heb ei dogfennu a weithiodd yn iawn yn anffurfiol yn dod yn rhwymedigaeth wirioneddol.

Busnes bach. Blaenoriaethwch ddogfennu eich system fwyaf dyngedfennol, leiaf-ddiangen sengl yn gyntaf, hyd yn oed yn anffurfiol, yn hytrach na cheisio dogfennaeth gynhwysfawr ar draws popeth. Mae dogfen fer, gywir yn cwmpasu eich pwynt methiant sengl mwyaf peryglus yn darparu mwy o werth gwirioneddol na gorchudd eang ond bas ym mhobman.

Menter. Mae hynafedd a darganfyddadwyedd dogfennaeth ill dau’n graddio’n wael yma, gan fod sefydliad mawr yn cronni dogfennaeth ar draws llawer o dimau a phlatfformau’n gyflymach nag y gall unrhyw un ei chadw’n gyfredol neu wedi’i threfnu’n gyson. Buddsoddwch mewn dadansoddeg platfform-dogfennaeth i olrhain mynediad a hynafedd ar raddfa, a thriniwch ddyled dogfennaeth fel categori dosbarth-cyntaf yn eich cronfa-waith dyled ar draws y sefydliad.

Llywodraeth. Gall deiliadaeth gyflogaeth hir sy’n gyffredin mewn sefydliadau sector cyhoeddus guddio risg gwybodaeth-heb-ei-dogfennu difrifol y tu ôl i sefydlogrwydd ymddangosiadol, gan y gallai system a gynhelir gan yr un person am bymtheg mlynedd weithredu’n berffaith iawn hyd nes i’r person hwnnw ymddeol. Triniwch iechyd dogfennaeth yn benodol fel pryder parhad-gweithrediadau, wedi’i gysylltu’n uniongyrchol â chynllunio gweithlu ac olyniaeth, nid dim ond hwylustod peirianneg.

Enghreifftiau

Menter. Darganfu cwmni gwasanaethau ariannol, yn ystod ad-drefnu diberthynas, nad oedd gan ei beiriant cyfrifo-risg craidd unrhyw ddogfennaeth ystyrlon y tu hwnt i ychydig o sylwadau cod hen ffasiwn, ac roedd y ddau beiriannydd a’i deallodd orau ill dau’n cael eu hail-neilltuo i fenter newydd ar yr un pryd. Tynnodd ymdrech ddogfennaeth frys, a gynhaliwyd o dan bwysau amser sylweddol, y wybodaeth ddyngedfennol a’i chofnodi cyn i’r ail-neilltuad ddod i rym, ond cymerodd y broses sawl wythnos o amser peiriannydd-uwch pwrpasol y gellid bod wedi’i ledaenu’n fwy graddol a rhad petai iechyd dogfennaeth wedi’i olrhain a’i flaenoriaethu’n rhagweithiol yn hytrach na’i ddarganfod fel argyfwng.

Llywodraeth. Roedd system rheoli-achosion ddegawdau oed llywodraeth talaith wedi cronni dogfennaeth sylweddol dros y blynyddoedd, ond canfu archwiliad darganfyddadwyedd nad oedd aelodau tîm newydd yn gyson yn gallu dod o hyd i ddogfennaeth berthnasol bresennol ac yn gofyn yr un llond llaw o gwestiynau’n ailadroddus mewn sianeli tîm, cwestiynau a oedd, mewn gwirionedd, eisoes wedi’u hateb yn rhywle ym mhlatfform dogfennaeth gwasgaredig, wedi’i drefnu’n wael yr asiantaeth. Yn hytrach nag ysgrifennu mwy o gynnwys, buddsoddodd yr asiantaeth mewn ail-drefnu a gwella strwythur chwilio a llywio ei dogfennaeth bresennol, a dangosodd arolwg dilynol ostyngiad mesuradwy mewn cwestiynau ailadroddus a phrofiad cynefino a adroddwyd yn ystyrlon gyflymach ar gyfer staff newydd, heb ychwanegu’r un dudalen newydd o gynnwys.

Achos busnes: cymhellion, ROI, a TCO

Cost argyfwng osgowyd yw’r enillion ar fesur a rheoli iechyd dogfennaeth yn fwriadol: mae’r enghraifft gwasanaethau ariannol uchod yn dangos y gwahaniaeth rhwng capio gwybodaeth rhagweithiol, graddol ac ymdrech argyfwng gywasgedig, ddrud a orfodwyd gan symudiad staff heb ei gynllunio. Mae gwybodaeth ddyngedfennol heb ei dogfennu’n rhwymedigaeth sefydlog sy’n costio dim yn weladwy hyd nes y foment y daw’n ddrud iawn ar unwaith.

Disgyblaeth olrhain y dirprwyon y mae’r pwnc hwn yn eu hargymell yn bennaf, patrymau mynediad, hynafedd, cwestiynau ailadroddus, amser cynefino, a’r parodrwydd i blygu bylchau dogfennaeth i mewn i gronfa- waith wedi’i blaenoriaethu yn hytrach na’u trin fel rhai statws-is yn barhaus o’u cymharu â gwaith sy’n canolbwyntio ar god, yw cost cyfanswm perchnogaeth. Mae’r ddisgyblaeth honno’n costio llawer llai na’r echdynnu gwybodaeth modd-argyfwng y mae’r enghraifft gwasanaethau ariannol yn ei ddangos fel y dewis arall.

Gwrth-batrymau a risgiau

Cyfrif bodolaeth dogfennaeth yn hytrach na defnyddioldeb: yn dweud bron dim byd wrthych am a yw gwybodaeth mewn gwirionedd yn hygyrch pan fo ei hangen.
Ysgrifennu mwy o gynnwys mewn ymateb i gwestiynau ailadroddus, heb wirio darganfyddadwyedd yn gyntaf: yn aml yn mynd i’r afael â’r broblem anghywir yn gyfan gwbl.
Byth yn gwirio hynafedd dogfennaeth mewn perthynas â faint mae’r system wedi newid: yn peryglu cynnwys camarweiniol yn weithredol, hen ffasiwn.
Trin dyled dogfennaeth fel un statws-is yn barhaus na dyled god: yn ei gadael wedi’i dan-flaenoriaethu’n gronig ac yn anweledig ar y gronfa-waith.
Camgymryd sefydlogrwydd ymddangosiadol, system nad yw wedi newid mewn blynyddoedd, am risg isel: gall guddio problem ffactor-bws difrifol, heb ei dogfennu y tu ôl i system nad yw ond eto wedi bod angen ei harbenigwr unigol.
Darganfod gwybodaeth ddyngedfennol heb ei dogfennu dim ond yn ystod trosglwyddiad staff brys: y modd methiant drud, osgoiadwy y mae’r pwnc hwn wedi’i adeiladu i’w atal.

Model aeddfedrwydd

Lefel 1, Cychwyn: Ni fesurir iechyd dogfennaeth; darganfyddir crynhoad gwybodaeth a risg hynafedd dim ond trwy argyfwng.
Lefel 2, Datblygu: Mae rhywfaint o ddogfennaeth yn bodoli, ond nid oes olrhain systematig o fynediad, hynafedd, na darganfyddadwyedd.
Lefel 3, Safoni: Olrheinir mynediad a hynafedd ar gyfer systemau dyngedfennol, a mesurir amser cynefino fel dirprwy ar gyfer iechyd gwybodaeth ar draws y sefydliad.
Lefel 4, Rheoli: Plygir bylchau dogfennaeth i mewn i’r gronfa- waith dyled dechnegol wedi’i blaenoriaethu, wedi’u croesgyfeirio â risg ffactor-bws i nodi’r risgiau cyfun mwyaf difrifol.
Lefel 5, Cerddorfaru: Mae’r sefydliad yn nodi ac yn mynd i’r afael â risg gwybodaeth-ddyngedfennol heb ei dogfennu’n rhagweithiol cyn i drosglwyddiad staffio orfodi’r mater, a gall bwyntio at welliannau cynefino neu ymateb-digwyddiad penodol, mesuradwy wedi’u holrhain at fuddsoddiad dogfennaeth.

Syniadau ar gyfer trafodaeth

Beth yw ein cyfuniad mwyaf difrifol sengl o ffactor bws isel a dogfennaeth wael ar hyn o bryd?
Pa gwestiwn a ofynnir yn ailadroddus er gwaethaf bod ateb dogfennedig yn bodoli?
Sut fyddem yn gwybod petai darn o ddogfennaeth dyngedfennol wedi mynd yn hen ffasiwn ac yn gamarweiniol?
A yw ein cronfa-waith dyled dechnegol yn cynnwys bylchau dogfennaeth, neu a ydynt yn anweledig?
Beth fyddai’n ei gostio i ni petai unig arbenigwr ein system leiaf-ddogfennedig yn gadael eleni?

Prif gasgliadau

Mesurwch ddefnyddioldeb, nid bodolaeth: a yw dogfennaeth mewn gwirionedd yn helpu, gan ddefnyddio dirprwyon fel patrymau mynediad, hynafedd, a chwestiynau ailadroddus.
Mae cwestiynau ailadroddus er gwaethaf atebion dogfennedig yn datgelu problem darganfyddadwyedd, nid o reidrwydd problem ymdrech- gynnwys.
Mae amser cynefino i gyfraniad cynhyrchiol yn ddirprwy cryf, ymarferol ar gyfer iechyd gwybodaeth cyffredinol.
Mae gwybodaeth ddyngedfennol heb ei dogfennu’n risg cyfansymio, yn enwedig wedi’i gyfuno â ffactor bws isel (pwnc 3.5); mae’n costio dim yn weladwy hyd nes iddo gostio llawer ar unwaith.
Plygwch fylchau dogfennaeth i mewn i’ch cronfa-waith dyled dechnegol (pwnc 4.5) fel eu bod yn cystadlu’n deg am gynhwysedd wedi’i flaenoriaethu.

Cyfeiriadau a darllen pellach

Docs for Developers: An Engineer’s Field Guide to Technical Writing, gan Jared Bhatti, Zachariah Goldberg, Ted Kubaska, a Sarah Moir (arferion dogfennaeth ymarferol ar gyfer timau peirianneg).
A Philosophy of Software Design, gan John Ousterhout (y berthynas rhwng dogfennaeth, cymhlethdod, a chynaliadwyedd).
Team Topologies, gan Matthew Skelton a Manuel Pais (goblygiadau dylunio sefydliadol gwybodaeth grynodedig yn erbyn un ddosbarthedig).
Accelerate: The Science of Lean Software and DevOps, gan Nicole Forsgren, Jez Humble, a Gene Kim (dogfennaeth fel un o’r galluoedd sy’n cydberthyn â pherfformiad cyflenwi).