4.6 Dokumentations- och kunskapsmätetal

Översikt och motivation

Det här ämnet avslutar del 4 genom att mäta om kunskapen som behövs för att säkert underhålla en kodbas faktiskt är dokumenterad och sökbar, inte bara om dokumentation tekniskt existerar någonstans. Ämne 3.5 täckte kommunikation och samarbete som en utvecklarupplevelseangelägenhet; det här ämnet täcker samma underliggande problem, kunskapstillgänglighet, från kodsidan: har en ny ingenjör, eller en befintlig som jobbar på obekant kod, vad de behöver för att göra en säker ändring, eller bor den kunskapen bara i huvudena på ett krympande antal erfarna personer.

Mätningsutmaningen här är genuint svår, svårare än de flesta andra mätetal i den här boken, eftersom dokumentationskvalitet och användbarhet är inherent mer subjektiva än en täckningsprocent eller en komplexitetspoäng. Det här ämnets tillvägagångssätt är att mäta representanter för användbarhet snarare än existens: hur ofta dokumentation faktiskt nås, hur ofta samma fråga ställs upprepade gånger trots att ett dokumenterat svar existerar, och hur lång tid det tar för någon obekant med ett system att bli produktiv i det. Ingen av de här representanterna är perfekt ensam, men tillsammans ger de en mycket ärligare bild än att räkna antalet wikisidor eller README-filer en kodbas innehåller.

För stora team ackumuleras det här ämnets angelägenheter med organisatorisk anställningstid och personalomsättning på sätt som är lätta att underskatta tills en kris tvingar fram frågan: ett system underhållet i åratal av samma två ingenjörer kan fungera perfekt med nästan ingen skriven dokumentation, ända tills båda de ingenjörerna slutar inom samma år, vid vilken punkt organisationen upptäcker att kunskapen aldrig faktiskt fångades någonstans varaktigt. Stora företag och myndigheter, med typiskt längre systemlivslängder och mindre säker personalkontinuitet än en startup, bär den här risken mer akut än de flesta.

Nyckelprinciper

Dokumentationsexistens är inte samma som dokumentationsanvändbarhet. Mät om den faktiskt hjälper, inte bara om den är närvarande.
Upprepade frågor trots dokumenterade svar avslöjar ett sökbarhetsproblem, inte ett dokumentationsinsatsproblem. Mer innehåll är inte alltid fixen.
Introduktionstid till produktivt bidrag är en stark, praktisk representant för övergripande kunskapshälsa, kopplande direkt till ämne 3.5:s samarbetsmätetal.
Kunskap som bara bor i människors huvuden är en varaktighetsrisk, inte ett stabilt, hållbart tillstånd, hur väl det än fungerar för närvarande.
Dokumentation förfaller. En sida som var korrekt för ett år sedan kan nu vara aktivt vilseledande, och föråldringen själv behöver spåras.

Rekommendationer

Spåra dokumentationsåtkomst och föråldring, inte bara existens

Där er dokumentationsplattform stödjer det, spåra hur ofta sidor faktiskt visas, och separat, hur länge sedan en sida senast uppdaterades relativt hur ofta det underliggande systemet den beskriver har ändrats (korsreferensering av churn-data från ämne 4.3 är direkt användbar här). En sida som beskriver ett system som har ändrats väsentligt sedan sidan senast redigerades är en stark kandidat för att vara aktivt vilseledande snarare än bara ohjälpsam, och den här föråldringssignalen förtjänar minst lika mycket uppmärksamhet som att spåra om dokumentation existerar alls.

Bevaka upprepade frågor som en sökbarhetssignal

Om samma fråga ställs upprepade gånger i en teamchattkanal eller under introduktion, trots att ett dokumenterat svar tekniskt existerar någonstans, avslöjar det mönstret ett sökbarhetsproblem, svaret är inte där människor naturligt letar efter det, snarare än ett dokumentationsinsatsproblem mer skrivande skulle fixa. Spåra återkommande frågor explicit, och använd dem för att prioritera att omorganisera eller bättre synliggöra befintligt innehåll över att skriva mer av det.

Mät introduktionstid till första meningsfulla, oberoende bidrag

Det här mätetalet, introducerat i ämne 3.5 som en samarbetssignal, är lika mycket en dokumentations- och kunskapshälsosignal från kodsidan. En konsekvent kort, förutsägbar introduktionstid antyder genuint tillgänglig, korrekt kunskap; en lång, högt varierande tid, särskilt en som beror tungt på vilken specifik person som råkar introducera en ny teammedlem, antyder kunskap som bor farligt koncentrerad i individuellt minne snarare än varaktig, skriven form.

Identifiera och prioritera odokumenterade kritisk-kunskap-områden explicit

Korsreferensera er kunskapskoncentrationsdata (ämne 3.5:s bussfaktor-analys) med dokumentationstäckning: ett system med en bussfaktor på ett och ingen meningsfull dokumentation är en allvarlig, ackumulerande risk som förtjänar prioriterad uppmärksamhet över ett väldokumenterat system med samma låga bussfaktor, eftersom dokumentationen åtminstone ger en partiell mildring medan en dedikerad efterträdare tränas.

Behandla dokumentationsskuld som en kategori inom er tekniska skuldbacklogg

Snarare än att spåra dokumentationsgap separat och informellt, väv betydande dokumentationsgap in i samma synliga, kvantifierade backlogg beskriven i ämne 4.5, särskilt för kritiska, låg-bussfaktor-system, så dokumentationsarbete konkurrerar rättvist om prioriterad kapacitet snarare än att evigt skjutas upp som en lägre-status-uppgift jämfört med kodfokuserad skuldåtgärd.

Avvägningar: fördelar och nackdelar

Tillvägagångssätt	Fördelar	Nackdelar
Ingen dokumentationsmätning	Låg overhead	Kunskapsrisk förblir osynlig tills en kris tvingar fram upptäckt
Att räkna dokumentationsexistens (sidantal, README-närvaro)	Enkelt, lätt att rapportera	Säger ingenting om användbarhet, korrekthet, eller sökbarhet
Spårning av åtkomst och föråldring	Avslöjar faktisk användbarhet och förfall	Kräver dokumentationsplattformsanalys och löpande granskningsdisciplin
Introduktionstid som en representant	Praktisk, konkret, kopplar direkt till verklig affärspåverkan	Indirekt; andra faktorer förutom dokumentation påverkar också introduktionshastighet

Den centrala spänningen är mätbarhet kontra mening. Dokumentationsexistens är trivialt lätt att räkna och berättar nästan ingenting användbart; genuin användbarhet, om någon faktiskt kan hitta och förlita sig på dokumenterad kunskap när de behöver den, är vad som faktiskt spelar roll men är svårare att mäta direkt. Lös spänningen genom att använda representanterna det här ämnet rekommenderar, åtkomstmönster, föråldring relativt churn, upprepade frågor, och introduktionstid, i kombination, accepterande att ingen enskild är perfekt men att deras konvergens är mycket mer meningsfull än ett existensantal ensamt.

Frågor att diskutera med ditt team

För vårt mest kritiska, lägst-bussfaktor-system, existerar meningsfull, korrekt dokumentation faktiskt, eller skulle en avgående expert ta med sig det mesta av den verkliga kunskapen? Det här är den skarpaste, mest konkreta versionen av det här ämnets centrala angelägenhet; besvara det ärligt för ert enskilt mest riskfyllda system först.
Vilken fråga ställs upprepade gånger i vår teamchatt trots att ett dokumenterat svar existerar någonstans? Om ni kan namnge en omedelbart är det ett sökbarhetsproblem värt att fixa direkt, troligen genom att omorganisera eller bättre synliggöra befintligt innehåll snarare än att skriva mer.
Hur lång tid tog det för vår senaste nya teammedlem att göra sitt första meningsfulla, oberoende bidrag, och hur jämförde det sig med teammedlemmen före dem? En stor, oförklarad varians mellan individer pekar ofta på kunskap som beror tungt på vem som råkar introducera någon, snarare än varaktig, tillgänglig dokumentation.
När kontrollerade vi senast om en dokumentationsbit fortfarande var korrekt, relativt hur mycket det underliggande systemet har ändrats sedan den skrevs? Om det ärliga svaret är “vi kontrollerar inte det här systematiskt” är den föråldringsrisken troligen större än någon för närvarande antar.
Inkluderar vår tekniska skuldbacklogg (ämne 4.5) dokumentationsgap, eller skjuts dokumentationsarbete evigt upp som en lägre-status-uppgift jämfört med kodfixar? Kontrollera er faktiska backlogg och se om dokumentationsskuld är synlig och konkurrerar om prioriterad kapacitet eller i praktiken osynlig.
Vad skulle det kosta oss om de en eller två personerna som förstår vårt mest kritiska, minst dokumenterade system slutade inom samma år? Den här konkreta, obekväma frågan är värd att besvara ärligt snarare än att behandla risken som abstrakt eller osannolik.

Sektorperspektiv

Startup. Formella dokumentationsmätetal är vanligtvis onödiga med ett litet team där kunskap sprids genom konstant, direkt konversation. Risken att bevaka är samma bussfaktorkoncentration ämne 3.5 varnar om, nu specifikt tillämpad på dokumentation: när teamet växer förbi storleken där alla pratar dagligen blir odokumenterad kunskap som fungerade fint informellt en verklig skuld.

Litet företag. Prioritera att dokumentera ert enskilt mest kritiska, minst redundanta system först, även informellt, snarare än att försöka heltäckande dokumentation över allt. Ett kort, korrekt dokument som täcker er mest riskfyllda enskilda felpunkt levererar mer verkligt värde än bred men ytlig täckning överallt.

Stort företag. Dokumentationsföråldring och sökbarhet skalar båda dåligt här, eftersom en stor organisation ackumulerar dokumentation över många team och plattformar snabbare än någon kan hålla den aktuell eller konsekvent organiserad. Investera i dokumentationsplattformsanalys för att spåra åtkomst och föråldring i skala, och behandla dokumentationsskuld som en förstklassig kategori i er organisationsövergripande skuldbacklogg.

Myndighet. Lång anställningstid vanlig i organisationer inom offentlig sektor kan maskera allvarlig odokumenterad-kunskap-risk bakom skenbar stabilitet, eftersom ett system underhållet av samma person i femton år kan fungera perfekt ända tills den personen går i pension. Behandla dokumentationshälsa explicit som en kontinuitet-i-verksamheten-angelägenhet, direkt kopplad till arbetskrafts- och efterträdarplanering, inte bara en ingenjörsfiness.

Exempel

Stort företag. Ett finanstjänstebolag upptäckte, under en orelaterad omorganisation, att dess kärnriskberäkningsmotor inte hade någon meningsfull dokumentation bortom några föråldrade kodkommentarer, och de två ingenjörerna som förstod den bäst omplacerades båda till ett nytt initiativ samtidigt. En akut dokumentationsinsats, genomförd under betydande tidspress, extraherade och registrerade den kritiska kunskapen innan omplaceringen trädde i kraft, men processen tog flera veckor av dedikerad senioringenjörstid som kunde ha spridits mer gradvis och billigt om dokumentationshälsa hade spårats och prioriterats proaktivt snarare än upptäckts som en nödsituation.

Myndighet. En delstatlig regerings decennier-gamla ärendehanteringssystem hade ackumulerat omfattande dokumentation över åren, men en sökbarhetsrevision fann att nya teammedlemmar konsekvent inte kunde hitta relevant befintlig dokumentation och upprepade gånger ställde samma handfull frågor i teamkanaler, frågor som faktiskt redan var besvarade någonstans i myndighetens sprawlande, dåligt organiserade dokumentationsplattform. Snarare än att skriva mer innehåll investerade myndigheten i att omorganisera och förbättra sök- och navigeringsstrukturen på sin befintliga dokumentation, och en uppföljande enkät visade en mätbar minskning i upprepade frågor och en meningsfullt snabbare rapporterad introduktionsupplevelse för ny personal, utan att lägga till en enda ny innehållssida.

Verksamhetsnytta: motiv, ROI och TCO

Avkastningen på att medvetet mäta och hantera dokumentationshälsa är undviken kriskostnad: finanstjänsteexemplet ovan visar skillnaden mellan proaktiv, gradvis kunskapsfångst och en dyr, komprimerad nödinsats tvingad av oplanerad personalrörelse. Odokumenterad kritisk kunskap är en stående skuld som inte kostar något synligt förrän i det ögonblick den blir mycket dyr på en gång.

Den totala ägandekostnaden är mestadels disciplinen av att spåra representanterna det här ämnet rekommenderar, åtkomstmönster, föråldring, upprepade frågor, introduktionstid, och viljan att väva dokumentationsgap in i en prioriterad backlogg snarare än att behandla dem som evigt lägre-status än kodfokuserat arbete. Den disciplinen kostar mycket mindre än kriskunskapsextraktionen finanstjänsteexemplet visar som alternativet.

Antimönster och fallgropar

Att räkna dokumentationsexistens snarare än användbarhet: berättar nästan ingenting om huruvida kunskap faktiskt är tillgänglig när behövd.
Att skriva mer innehåll som respons på upprepade frågor, utan att först kontrollera sökbarhet: adresserar ofta helt fel problem.
Att aldrig kontrollera dokumentationsföråldring relativt hur mycket systemet har ändrats: riskerar aktivt vilseledande, föråldrat innehåll.
Att behandla dokumentationsskuld som evigt lägre-status än kodskuld: lämnar den kroniskt nedprioriterad och osynlig på backloggen.
Att misstaga skenbar stabilitet, ett system som inte har ändrats på år, för låg risk: kan maskera ett allvarligt, odokumenterat bussfaktorproblem bakom ett system som helt enkelt ännu inte har behövt sin ende expert.
Att upptäcka kritisk odokumenterad kunskap bara under en nödsituationspersonalövergång: det dyra, undvikbara felmönstret det här ämnet är byggt att förhindra.

Mognadsmodell

Nivå 1, Initiera: Dokumentationshälsa mäts inte; kunskapskoncentration och föråldringsrisk upptäcks bara genom kris.
Nivå 2, Utveckla: Viss dokumentation existerar, men det finns ingen systematisk spårning av åtkomst, föråldring, eller sökbarhet.
Nivå 3, Standardisera: Åtkomst och föråldring spåras för kritiska system, och introduktionstid mäts som en representant för kunskapshälsa organisationsövergripande.
Nivå 4, Hantera: Dokumentationsgap vävs in i den prioriterade tekniska skuldbackloggen, korsrefererade med bussfaktorrisk för att identifiera de mest allvarliga kombinerade riskerna.
Nivå 5, Orkestrera: Organisationen identifierar och adresserar proaktivt odokumenterad kritisk-kunskap-risk innan en personalövergång tvingar fram frågan, och kan peka på specifika, mätbara introduktions- eller incidentresponsförbättringar spårade till dokumentationsinvestering.

Diskussionsidéer

Vad är vår enskilt mest allvarliga kombination av låg bussfaktor och dålig dokumentation just nu?
Vilken fråga ställs upprepade gånger trots att ett dokumenterat svar existerar?
Hur skulle vi veta om en kritisk dokumentationsbit hade blivit föråldrad och vilseledande?
Inkluderar vår tekniska skuldbacklogg dokumentationsgap, eller är de osynliga?
Vad skulle det kosta oss om vårt minst dokumenterade systems ende expert slutade i år?

Viktiga slutsatser

Mät användbarhet, inte existens: om dokumentation faktiskt hjälper, med hjälp av representanter som åtkomstmönster, föråldring, och upprepade frågor.
Upprepade frågor trots dokumenterade svar avslöjar ett sökbarhetsproblem, inte nödvändigtvis ett innehållsinsatsproblem.
Introduktionstid till produktivt bidrag är en stark, praktisk representant för övergripande kunskapshälsa.
Odokumenterad kritisk kunskap är en ackumulerande risk, särskilt kombinerad med en låg bussfaktor (ämne 3.5); den kostar ingenting synligt förrän den kostar mycket på en gång.
Väv in dokumentationsgap i er tekniska skuldbacklogg (ämne 4.5) så de konkurrerar rättvist om prioriterad kapacitet.

Källor och vidare läsning

Docs for Developers: An Engineer’s Field Guide to Technical Writing, av Jared Bhatti, Zachariah Goldberg, Ted Kubaska, och Sarah Moir (praktisk dokumentationspraxis för ingenjörsteam).
A Philosophy of Software Design, av John Ousterhout (förhållandet mellan dokumentation, komplexitet, och underhållbarhet).
Team Topologies, av Matthew Skelton och Manuel Pais (organisatoriska designimplikationer av koncentrerad kontra distribuerad kunskap).
Accelerate: The Science of Lean Software and DevOps, av Nicole Forsgren, Jez Humble, och Gene Kim (dokumentation som en av förmågorna korrelerade med leveransprestation).