4.6 दस्तावेज़ीकरण और ज्ञान मेट्रिक्स

अवलोकन और प्रेरणा

यह विषय यह मापकर भाग 4 को समाप्त करता है कि क्या एक कोडबेस को सुरक्षित रूप से बनाए रखने के लिए आवश्यक ज्ञान वास्तव में दस्तावेज़ीकृत और खोजने योग्य है, केवल यह नहीं कि क्या दस्तावेज़ीकरण तकनीकी रूप से कहीं मौजूद है। विषय 3.5 ने एक डेवलपर-अनुभव चिंता के रूप में संचार और सहयोग को कवर किया; यह विषय कोड पक्ष से उसी अंतर्निहित मुद्दे, ज्ञान उपलब्धता, को कवर करता है: क्या एक नए इंजीनियर, या अपरिचित कोड पर काम करने वाले एक मौजूदा इंजीनियर, के पास एक सुरक्षित परिवर्तन करने के लिए वह है जो उन्हें चाहिए, या वह ज्ञान केवल सिकुड़ते कार्यकालीन लोगों की एक संख्या के दिमाग़ों में रहता है।

यहाँ माप चुनौती वास्तव में कठिन है, इस पुस्तक के अधिकांश अन्य मेट्रिक्स से कठिन, क्योंकि दस्तावेज़ीकरण गुणवत्ता और उपयोगिता एक कवरेज प्रतिशत या एक जटिलता स्कोर से अंतर्निहित रूप से अधिक व्यक्तिपरक हैं। इस विषय का दृष्टिकोण अस्तित्व की बजाय उपयोगिता के लिए प्रॉक्सी मापना है: दस्तावेज़ीकरण को वास्तव में कितनी बार एक्सेस किया जाता है, एक दस्तावेज़ीकृत उत्तर मौजूद होने के बावजूद वही प्रश्न कितनी बार बार-बार पूछा जाता है, और एक प्रणाली से अपरिचित किसी व्यक्ति को इसमें उत्पादक बनने में कितना समय लगता है। इनमें से कोई भी प्रॉक्सी अकेले पूर्ण नहीं है, लेकिन साथ में वे एक कोडबेस में शामिल विकी पन्नों या README फ़ाइलों की संख्या गिनने से कहीं अधिक ईमानदार तस्वीर देते हैं।

बड़ी टीमों के लिए, इस विषय की चिंताएँ संगठनात्मक कार्यकाल और टर्नओवर के साथ ऐसे तरीक़ों से संयोजित होती हैं जिन्हें एक संकट मुद्दे को मजबूर करने तक कम आँकना आसान है: एक प्रणाली जिसे वर्षों तक उन्हीं दो इंजीनियरों द्वारा बनाए रखा गया वह लगभग कोई लिखित दस्तावेज़ीकरण न होने के बावजूद पूरी तरह ठीक काम कर सकती है, ठीक तब तक जब तक वे दोनों इंजीनियर उसी वर्ष में छोड़ नहीं देते, जिस बिंदु पर संगठन खोजता है कि ज्ञान वास्तव में कभी कहीं टिकाऊ रूप से कैप्चर नहीं किया गया था। एंटरप्राइज़ और सरकारी संगठन, आमतौर पर एक स्टार्टअप की तुलना में लंबे प्रणाली जीवनकाल और कम निश्चित स्टाफ़ निरंतरता के साथ, इस जोखिम को अधिकांश से अधिक तीव्रता से ले जाते हैं।

प्रमुख सिद्धांत

• दस्तावेज़ीकरण अस्तित्व दस्तावेज़ीकरण उपयोगिता के समान नहीं है। मापें कि क्या यह वास्तव में मदद करता है, केवल यह नहीं कि क्या यह मौजूद है।
• दस्तावेज़ीकृत उत्तरों के बावजूद बार-बार होने वाले प्रश्न एक खोजने-योग्यता समस्या उजागर करते हैं, एक दस्तावेज़ीकरण-प्रयास समस्या नहीं। अधिक सामग्री हमेशा समाधान नहीं है।
• उत्पादक योगदान तक ऑनबोर्डिंग समय समग्र ज्ञान स्वास्थ्य के लिए एक मज़बूत, व्यावहारिक प्रॉक्सी है, विषय 3.5 के सहयोग मेट्रिक्स से सीधे जुड़ते हुए।
• ज्ञान जो केवल लोगों के दिमाग़ों में रहता है वह एक टिकाऊपन जोखिम है, एक स्थिर, टिकाऊ स्थिति नहीं, चाहे यह वर्तमान में कितनी भी अच्छी तरह कार्य करे।
• दस्तावेज़ीकरण क्षय होता है। एक पन्ना जो एक वर्ष पहले सटीक था वह अब सक्रिय रूप से गुमराह कर सकता है, और पुरानापन स्वयं ट्रैक किए जाने की आवश्यकता है।

सिफ़ारिशें

केवल अस्तित्व नहीं, दस्तावेज़ीकरण एक्सेस और पुरानापन ट्रैक करें

जहाँ आपका दस्तावेज़ीकरण प्लेटफ़ॉर्म इसका समर्थन करता है, ट्रैक करें कि पन्नों को वास्तव में कितनी बार देखा जाता है, और अलग से, यह वर्णन करने वाली अंतर्निहित प्रणाली कितनी बार बदली है इसके सापेक्ष एक पन्ने को अंतिम बार अपडेट हुए कितना समय हुआ है (विषय 4.3 से चर्न डेटा को क्रॉस-रेफ़रेंस करना यहाँ सीधे उपयोगी है)। एक प्रणाली का वर्णन करने वाला एक पन्ना जो पन्ने के अंतिम बार संपादित होने के बाद काफ़ी बदल गया है वह केवल अनुपयोगी होने की बजाय सक्रिय रूप से गुमराह करने वाला होने का एक मज़बूत उम्मीदवार है, और यह पुरानापन संकेत कम से कम उतना ध्यान देने योग्य है जितना यह ट्रैक करना कि दस्तावेज़ीकरण बिल्कुल मौजूद है।

एक खोजने-योग्यता संकेत के रूप में बार-बार होने वाले प्रश्नों के लिए देखें

यदि एक टीम चैट चैनल में या ऑनबोर्डिंग के दौरान वही प्रश्न बार-बार पूछा जाता है, एक दस्तावेज़ीकृत उत्तर तकनीकी रूप से कहीं मौजूद होने के बावजूद, वह पैटर्न एक खोजने-योग्यता समस्या उजागर करता है, उत्तर वहाँ नहीं है जहाँ लोग स्वाभाविक रूप से इसे देखते हैं, एक दस्तावेज़ीकरण-प्रयास समस्या नहीं जिसे अधिक लेखन ठीक कर देगा। बार-बार होने वाले प्रश्नों को स्पष्ट रूप से ट्रैक करें, और अधिक लिखने की बजाय मौजूदा सामग्री को पुनर्गठित करने या बेहतर उजागर करने को प्राथमिकता देने के लिए उनका उपयोग करें।

पहले सार्थक, स्वतंत्र योगदान तक ऑनबोर्डिंग समय मापें

यह मेट्रिक, विषय 3.5 में एक सहयोग संकेत के रूप में पेश किया गया, समान रूप से कोड पक्ष से एक दस्तावेज़ीकरण और ज्ञान-स्वास्थ्य संकेत भी है। लगातार एक छोटा, अनुमानित ऑनबोर्डिंग समय वास्तव में सुलभ, सटीक ज्ञान का सुझाव देता है; एक लंबा, अत्यधिक परिवर्तनशील समय, विशेष रूप से एक जो बहुत हद तक इस पर निर्भर करता है कि कौन-सा विशिष्ट व्यक्ति एक नए टीम सदस्य को ऑनबोर्ड करता है, ऐसे ज्ञान का सुझाव देता है जो टिकाऊ, लिखित रूप की बजाय ख़तरनाक रूप से व्यक्तिगत याददाश्त में केंद्रित रहता है।

अदस्तावेज़ीकृत महत्वपूर्ण-ज्ञान क्षेत्रों की स्पष्ट रूप से पहचान और प्राथमिकता करें

अपने ज्ञान-एकाग्रता डेटा (विषय 3.5 का बस-फ़ैक्टर विश्लेषण) को दस्तावेज़ीकरण कवरेज के साथ क्रॉस-रेफ़रेंस करें: एक की बस फ़ैक्टर और कोई सार्थक दस्तावेज़ीकरण न होने वाली एक प्रणाली एक गंभीर, संयोजित जोखिम है जो उसी कम बस फ़ैक्टर वाली एक अच्छी तरह-दस्तावेज़ीकृत प्रणाली की तुलना में प्राथमिकता ध्यान की हक़दार है, क्योंकि दस्तावेज़ीकरण कम से कम एक आंशिक शमन प्रदान करता है जबकि एक समर्पित उत्तराधिकारी प्रशिक्षित किया जाता है।

दस्तावेज़ीकरण ऋण को अपने तकनीकी ऋण बैकलॉग के भीतर एक श्रेणी मानें

दस्तावेज़ीकरण अंतरों को अलग से और अनौपचारिक रूप से ट्रैक करने की बजाय, महत्वपूर्ण दस्तावेज़ीकरण अंतरों को विषय 4.5 में वर्णित उसी दृश्यमान, मात्रात्मक बैकलॉग में मोड़ें, विशेष रूप से महत्वपूर्ण, कम-बस-फ़ैक्टर प्रणालियों के लिए, ताकि दस्तावेज़ीकरण कार्य कोड-केंद्रित ऋण उपचार की तुलना में एक निम्न-स्थिति कार्य के रूप में स्थायी रूप से टाले जाने की बजाय प्राथमिकता प्राप्त क्षमता के लिए निष्पक्ष रूप से प्रतिस्पर्धा करे।

समझौते: लाभ और हानि

दृष्टिकोण	लाभ	हानि
कोई दस्तावेज़ीकरण माप नहीं	कम ओवरहेड	ज्ञान जोखिम एक संकट खोज को मजबूर करने तक अदृश्य रहता है
दस्तावेज़ीकरण अस्तित्व गिनना (पन्ना गिनती, README उपस्थिति)	सरल, रिपोर्ट करना आसान	उपयोगिता, सटीकता, या खोजने-योग्यता के बारे में कुछ नहीं बताता
एक्सेस और पुरानापन ट्रैकिंग	वास्तविक उपयोगिता और क्षय उजागर करती है	दस्तावेज़ीकरण-प्लेटफ़ॉर्म एनालिटिक्स और निरंतर समीक्षा अनुशासन की आवश्यकता
ऑनबोर्डिंग समय एक प्रॉक्सी के रूप में	व्यावहारिक, ठोस, वास्तविक व्यावसायिक प्रभाव से सीधे जुड़ता है	अप्रत्यक्ष; दस्तावेज़ीकरण के अलावा अन्य कारक भी ऑनबोर्डिंग गति को प्रभावित करते हैं

केंद्रीय तनाव है मापनीयता बनाम अर्थ। दस्तावेज़ीकरण अस्तित्व गिनना तुच्छ रूप से आसान है और आपको लगभग कुछ भी उपयोगी नहीं बताता; वास्तविक उपयोगिता, क्या कोई वास्तव में दस्तावेज़ीकृत ज्ञान को खोज और भरोसा कर सकता है जब उन्हें इसकी आवश्यकता है, वह है जो वास्तव में मायने रखता है लेकिन सीधे मापना कठिन है। तनाव को इस विषय द्वारा सुझाए गए प्रॉक्सी, एक्सेस पैटर्न, चर्न के सापेक्ष पुरानापन, बार-बार होने वाले प्रश्न, और ऑनबोर्डिंग समय, को संयोजन में उपयोग करके हल करें, यह स्वीकार करते हुए कि कोई भी एक अकेला पूर्ण नहीं है लेकिन उनका अभिसरण अकेले एक अस्तित्व गिनती से कहीं अधिक अर्थपूर्ण है।

अपनी टीम के साथ चर्चा करने के प्रश्न

1. हमारी सबसे महत्वपूर्ण, सबसे कम-बस-फ़ैक्टर प्रणाली के लिए, क्या सार्थक, सटीक दस्तावेज़ीकरण वास्तव में मौजूद है, या क्या एक जाने वाला विशेषज्ञ अधिकांश वास्तविक ज्ञान अपने साथ ले जाएगा? यह इस विषय की केंद्रीय चिंता का सबसे तीव्र, सबसे ठोस संस्करण है; पहले अपनी एकल सबसे जोखिम भरी प्रणाली के लिए इसका ईमानदारी से उत्तर दें।

2. हमारी टीम चैट में एक दस्तावेज़ीकृत उत्तर कहीं मौजूद होने के बावजूद कौन-सा प्रश्न बार-बार पूछा जाता है? यदि आप तुरंत एक का नाम ले सकते हैं, तो वह सीधे ठीक करने लायक़ एक खोजने-योग्यता समस्या है, संभवतः अधिक लिखने की बजाय मौजूदा सामग्री को पुनर्गठित करने या बेहतर उजागर करने से।

3. हमारे सबसे हाल के नए टीम सदस्य को अपना पहला सार्थक, स्वतंत्र योगदान देने में कितना समय लगा, और यह उनसे पहले के टीम सदस्य से कैसे तुलना करता है? व्यक्तियों के बीच एक बड़ी, अस्पष्टीकृत भिन्नता अक्सर उस ज्ञान की ओर इशारा करती है जो टिकाऊ, सुलभ दस्तावेज़ीकरण की बजाय इस पर बहुत हद तक निर्भर करता है कि कौन किसी को ऑनबोर्ड करता है।

4. हमने आख़िरी बार कब जाँचा था कि क्या दस्तावेज़ीकरण का एक टुकड़ा अभी भी सटीक था, इसके लिखे जाने के बाद अंतर्निहित प्रणाली कितनी बदली है इसके सापेक्ष? यदि ईमानदार उत्तर है “हम इसे व्यवस्थित रूप से नहीं जाँचते,” तो वह पुरानापन जोखिम संभवतः किसी की वर्तमान धारणा से बड़ा है।

5. क्या हमारे तकनीकी ऋण बैकलॉग (विषय 4.5) में दस्तावेज़ीकरण अंतर शामिल हैं, या दस्तावेज़ीकरण कार्य कोड सुधारों की तुलना में एक निम्न-स्थिति कार्य के रूप में स्थायी रूप से टाला जाता है? अपने वास्तविक बैकलॉग की जाँच करें और देखें कि क्या दस्तावेज़ीकरण ऋण दृश्यमान है और प्राथमिकता प्राप्त क्षमता के लिए प्रतिस्पर्धा कर रहा है या प्रभावी रूप से अदृश्य है।

6. यदि वे एक या दो लोग जो हमारी सबसे महत्वपूर्ण, सबसे कम-दस्तावेज़ीकृत प्रणाली को समझते हैं उसी वर्ष में छोड़ दें तो हमें क्या क़ीमत चुकानी पड़ेगी? यह ठोस, असहज प्रश्न जोखिम को अमूर्त या असंभावित मानने की बजाय ईमानदारी से उत्तर देने लायक़ है।

क्षेत्र दृष्टिकोण

स्टार्टअप। एक छोटी टीम के साथ जहाँ ज्ञान निरंतर, प्रत्यक्ष बातचीत के माध्यम से फैलता है, औपचारिक दस्तावेज़ीकरण मेट्रिक्स आमतौर पर अनावश्यक हैं। जिस जोखिम पर नज़र रखनी है वह वही बस-फ़ैक्टर एकाग्रता है जिसके बारे में विषय 3.5 चेतावनी देता है, अब विशेष रूप से दस्तावेज़ीकरण पर लागू: जैसे-जैसे टीम उस आकार से आगे बढ़ती है जहाँ हर कोई प्रतिदिन बात करता है, अदस्तावेज़ीकृत ज्ञान जो अनौपचारिक रूप से ठीक काम करता था वह एक वास्तविक देनदारी बन जाता है।

छोटा व्यवसाय। सब कुछ में व्यापक दस्तावेज़ीकरण का प्रयास करने की बजाय, यहाँ तक कि अनौपचारिक रूप से भी, पहले अपनी एकल सबसे महत्वपूर्ण, सबसे कम-अनावश्यक प्रणाली का दस्तावेज़ीकरण करने को प्राथमिकता दें। आपके सबसे जोखिम भरे एकल विफलता बिंदु को कवर करने वाला एक संक्षिप्त, सटीक दस्तावेज़ हर जगह व्यापक लेकिन उथले कवरेज से अधिक वास्तविक मूल्य पहुँचाता है।

एंटरप्राइज़। यहाँ दस्तावेज़ीकरण पुरानापन और खोजने-योग्यता दोनों बुरी तरह पैमाना बदलते हैं, क्योंकि एक बड़ा संगठन कई टीमों और प्लेटफ़ॉर्मों में दस्तावेज़ीकरण जमा करता है इससे तेज़ी से कि कोई भी इसे वर्तमान या लगातार व्यवस्थित रख सके। पैमाने पर एक्सेस और पुरानापन ट्रैक करने के लिए दस्तावेज़ीकरण-प्लेटफ़ॉर्म एनालिटिक्स में निवेश करें, और दस्तावेज़ीकरण ऋण को अपने संगठन-व्यापी ऋण बैकलॉग में एक प्रथम-श्रेणी श्रेणी मानें।

सरकार। सार्वजनिक-क्षेत्र संगठनों में सामान्य लंबे कर्मचारी कार्यकाल स्पष्ट स्थिरता के पीछे गंभीर अदस्तावेज़ीकृत-ज्ञान जोखिम छुपा सकते हैं, क्योंकि पंद्रह वर्षों तक उसी व्यक्ति द्वारा बनाए रखी गई एक प्रणाली उस व्यक्ति के सेवानिवृत्त होने तक पूरी तरह ठीक काम कर सकती है। दस्तावेज़ीकरण स्वास्थ्य को स्पष्ट रूप से एक परिचालन-निरंतरता चिंता मानें, कार्यबल और उत्तराधिकार योजना से सीधे जुड़ा हुआ, केवल एक इंजीनियरिंग शालीनता नहीं।

उदाहरण

एंटरप्राइज़। एक वित्तीय सेवा कंपनी ने, एक असंबंधित पुनर्गठन के दौरान, खोजा कि इसके मुख्य जोखिम-गणना इंजन में कुछ पुरानी कोड टिप्पणियों से परे कोई सार्थक दस्तावेज़ीकरण नहीं था, और इसे सबसे अच्छी तरह समझने वाले दो इंजीनियरों दोनों को एक साथ एक नई पहल में पुनर्नियुक्त किया जा रहा था। एक आपातकालीन दस्तावेज़ीकरण प्रयास, महत्वपूर्ण समय दबाव के तहत आयोजित, ने पुनर्नियुक्ति प्रभावी होने से पहले महत्वपूर्ण ज्ञान निकाला और दर्ज किया, लेकिन प्रक्रिया में समर्पित वरिष्ठ-इंजीनियर समय के कई सप्ताह लगे जिसे अधिक धीरे-धीरे और सस्ते में फैलाया जा सकता था यदि दस्तावेज़ीकरण स्वास्थ्य को सक्रिय रूप से ट्रैक और प्राथमिकता दी गई होती एक आपातकाल के रूप में खोजे जाने की बजाय।

सरकार। एक राज्य सरकार की दशकों पुरानी केस-प्रबंधन प्रणाली ने वर्षों में पर्याप्त दस्तावेज़ीकरण जमा किया था, लेकिन एक खोजने-योग्यता ऑडिट ने पाया कि नए टीम सदस्य लगातार प्रासंगिक मौजूदा दस्तावेज़ीकरण नहीं खोज पाते थे और टीम चैनलों में बार-बार वही मुट्ठी भर प्रश्न पूछते थे, ऐसे प्रश्न जिनका, वास्तव में, एजेंसी के व्यापक, ख़राब व्यवस्थित दस्तावेज़ीकरण प्लेटफ़ॉर्म में कहीं पहले से उत्तर दिया जा चुका था। अधिक सामग्री लिखने की बजाय, एजेंसी ने अपने मौजूदा दस्तावेज़ीकरण की खोज और नेविगेशन संरचना को पुनर्गठित और सुधारने में निवेश किया, और एक अनुवर्ती सर्वेक्षण ने बार-बार होने वाले प्रश्नों में एक मापने योग्य कमी और नए स्टाफ़ के लिए एक सार्थक रूप से तेज़ रिपोर्ट किया गया ऑनबोर्डिंग अनुभव दिखाया, सामग्री का एक भी नया पन्ना जोड़े बिना।

व्यावसायिक तर्क: प्रेरणाएँ, ROI, और TCO

दस्तावेज़ीकरण स्वास्थ्य को जान-बूझकर मापने और प्रबंधित करने का प्रतिफल टाली गई संकट लागत है: ऊपर का वित्तीय सेवा उदाहरण सक्रिय, धीरे-धीरे ज्ञान कैप्चर और अनियोजित स्टाफ़ आंदोलन द्वारा मजबूर एक महंगे, संकुचित आपातकालीन प्रयास के बीच का अंतर दिखाता है। अदस्तावेज़ीकृत महत्वपूर्ण ज्ञान एक स्थायी देनदारी है जो उस क्षण तक कुछ भी दृश्यमान रूप से ख़र्च नहीं करती जब तक यह एक साथ बहुत महंगी नहीं बन जाती।

कुल स्वामित्व लागत अधिकांशतः इस विषय द्वारा सुझाए गए प्रॉक्सी, एक्सेस पैटर्न, पुरानापन, बार-बार होने वाले प्रश्न, ऑनबोर्डिंग समय, को ट्रैक करने का अनुशासन है, और दस्तावेज़ीकरण अंतरों को कोड-केंद्रित काम की तुलना में स्थायी रूप से निम्न-स्थिति मानने की बजाय एक प्राथमिकता प्राप्त बैकलॉग में मोड़ने की इच्छा है। वह अनुशासन उस संकट-मोड ज्ञान निष्कर्षण से कहीं कम लागत लेता है जिसे वित्तीय सेवा उदाहरण विकल्प के रूप में दिखाता है।

विरोधी-पैटर्न और नुक़सान

• उपयोगिता की बजाय दस्तावेज़ीकरण अस्तित्व गिनना: यह लगभग कुछ नहीं बताता कि क्या ज्ञान वास्तव में आवश्यकता पड़ने पर सुलभ है।
• पहले खोजने-योग्यता जाँचे बिना बार-बार होने वाले प्रश्नों के जवाब में अधिक सामग्री लिखना: अक्सर पूरी तरह ग़लत समस्या को संबोधित करता है।
• यह जाँचे बिना कि प्रणाली कितनी बदली है, दस्तावेज़ीकरण पुरानापन कभी न जाँचना: सक्रिय रूप से गुमराह करने वाली, पुरानी सामग्री का जोखिम रखता है।
• दस्तावेज़ीकरण ऋण को कोड ऋण की तुलना में स्थायी रूप से निम्न-स्थिति मानना: इसे बैकलॉग पर दीर्घकालिक रूप से अप्राथमिकता प्राप्त और अदृश्य छोड़ देता है।
• स्पष्ट स्थिरता, एक प्रणाली जो वर्षों में नहीं बदली है, को कम जोखिम समझने की ग़लती: एक गंभीर, अदस्तावेज़ीकृत बस-फ़ैक्टर समस्या को उस प्रणाली के पीछे छुपा सकता है जिसे बस अभी तक अपने एकमात्र विशेषज्ञ की आवश्यकता नहीं पड़ी है।
• केवल एक आपातकालीन स्टाफ़ संक्रमण के दौरान महत्वपूर्ण अदस्तावेज़ीकृत ज्ञान की खोज करना: महंगा, टालने योग्य विफलता मोड जिसे रोकने के लिए यह विषय बनाया गया है।

परिपक्वता मॉडल

• स्तर 1, आरंभ: दस्तावेज़ीकरण स्वास्थ्य को नहीं मापा जाता; ज्ञान एकाग्रता और पुरानापन जोखिम केवल संकट के माध्यम से खोजे जाते हैं।
• स्तर 2, विकास: कुछ दस्तावेज़ीकरण मौजूद है, लेकिन एक्सेस, पुरानापन, या खोजने-योग्यता की कोई व्यवस्थित ट्रैकिंग नहीं है।
• स्तर 3, मानकीकरण: महत्वपूर्ण प्रणालियों के लिए एक्सेस और पुरानापन को ट्रैक किया जाता है, और ऑनबोर्डिंग समय को संगठन-व्यापी ज्ञान स्वास्थ्य के लिए एक प्रॉक्सी के रूप में मापा जाता है।
• स्तर 4, प्रबंधन: दस्तावेज़ीकरण अंतरों को सबसे गंभीर संयुक्त जोखिमों की पहचान करने के लिए बस-फ़ैक्टर जोखिम के साथ क्रॉस-रेफ़रेंस किए गए प्राथमिकता प्राप्त तकनीकी ऋण बैकलॉग में मोड़ा जाता है।
• स्तर 5, संयोजन: संगठन एक स्टाफ़िंग संक्रमण द्वारा मुद्दे को मजबूर करने से पहले सक्रिय रूप से अदस्तावेज़ीकृत महत्वपूर्ण-ज्ञान जोखिम की पहचान और संबोधन करता है, और दस्तावेज़ीकरण निवेश से ट्रेस किए गए विशिष्ट, मापने योग्य ऑनबोर्डिंग या घटना-प्रतिक्रिया सुधारों की ओर इशारा कर सकता है।

चर्चा के लिए विचार

1. अभी कम बस फ़ैक्टर और ख़राब दस्तावेज़ीकरण का हमारा एकल सबसे गंभीर संयोजन क्या है?
2. कौन-सा प्रश्न एक दस्तावेज़ीकृत उत्तर मौजूद होने के बावजूद बार-बार पूछा जाता है?
3. हमें कैसे पता चलेगा यदि महत्वपूर्ण दस्तावेज़ीकरण का एक टुकड़ा पुराना और गुमराह करने वाला हो गया है?
4. क्या हमारे तकनीकी ऋण बैकलॉग में दस्तावेज़ीकरण अंतर शामिल हैं, या वे अदृश्य हैं?
5. यदि हमारी सबसे कम-दस्तावेज़ीकृत प्रणाली का एकमात्र विशेषज्ञ इस वर्ष छोड़ दे तो हमें क्या क़ीमत चुकानी पड़ेगी?

मुख्य निष्कर्ष

• उपयोगिता मापें, अस्तित्व नहीं: क्या दस्तावेज़ीकरण वास्तव में मदद करता है, एक्सेस पैटर्न, पुरानापन, और बार-बार होने वाले प्रश्नों जैसे प्रॉक्सी का उपयोग करते हुए।
• दस्तावेज़ीकृत उत्तरों के बावजूद बार-बार होने वाले प्रश्न एक खोजने-योग्यता समस्या उजागर करते हैं, आवश्यक रूप से एक सामग्री-प्रयास समस्या नहीं।
• उत्पादक योगदान तक ऑनबोर्डिंग समय समग्र ज्ञान स्वास्थ्य के लिए एक मज़बूत, व्यावहारिक प्रॉक्सी है।
• अदस्तावेज़ीकृत महत्वपूर्ण ज्ञान एक संयोजित जोखिम है, विशेष रूप से एक कम बस फ़ैक्टर (विषय 3.5) के साथ संयुक्त; यह तब तक कुछ भी दृश्यमान रूप से ख़र्च नहीं करता जब तक यह एक साथ बहुत कुछ ख़र्च नहीं कर देता।
• दस्तावेज़ीकरण अंतरों को अपने तकनीकी ऋण बैकलॉग में मोड़ें (विषय 4.5) ताकि वे प्राथमिकता प्राप्त क्षमता के लिए निष्पक्ष रूप से प्रतिस्पर्धा करें।

संदर्भ और आगे पढ़ने के लिए

• Docs for Developers: An Engineer’s Field Guide to Technical Writing, by Jared Bhatti, Zachariah Goldberg, Ted Kubaska, and Sarah Moir (इंजीनियरिंग टीमों के लिए व्यावहारिक दस्तावेज़ीकरण प्रथाएँ)।
• A Philosophy of Software Design, by John Ousterhout (दस्तावेज़ीकरण, जटिलता, और रखरखाव-योग्यता के बीच संबंध)।
• Team Topologies, by Matthew Skelton and Manuel Pais (केंद्रित बनाम वितरित ज्ञान के संगठनात्मक डिज़ाइन प्रभाव)।
• Accelerate: The Science of Lean Software and DevOps, by Nicole Forsgren, Jez Humble, and Gene Kim (डिलीवरी प्रदर्शन से सहसंबंधित क्षमताओं में से एक के रूप में दस्तावेज़ीकरण)।