हमने प्रलेखन की गुणवत्ता का मूल्यांकन कैसे किया

नमस्कार, हेब्र! मेरा नाम लेशा है, मैं अल्फा-बैंक की उत्पाद टीमों में से एक में एक सिस्टम विश्लेषक हूं। अब मैं कानूनी संस्थाओं और व्यक्तिगत उद्यमियों के लिए एक नया इंटरनेट बैंक विकसित कर रहा हूं।

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



हालांकि, स्पष्ट कारणों के लिए प्रलेखन को नजरअंदाज नहीं किया जा सकता है। और हमारे जीवन को सरल बनाने के लिए, हमने प्रलेखन की गुणवत्ता का आकलन करने का निर्णय लिया। हमने वास्तव में यह कैसे किया और हम किस निष्कर्ष पर पहुंचे - कट के तहत।

प्रलेखन गुणवत्ता

कई दर्जन बार पाठ "न्यू इंटरनेट बैंक" को दोहराने के लिए, मैं एनआईबी लिखूंगा। अब हमारे पास उद्यमियों और कानूनी संस्थाओं के लिए NIB के विकास पर काम करने वाली एक दर्जन से अधिक टीमें हैं। इसके अलावा, उनमें से प्रत्येक या तो खरोंच से एक नई सेवा या वेब अनुप्रयोग के लिए अपना स्वयं का दस्तावेज बनाता है, या वर्तमान में परिवर्तन करता है। इस दृष्टिकोण के साथ, सिद्धांत में प्रलेखन उच्च गुणवत्ता का हो सकता है?

और प्रलेखन की गुणवत्ता निर्धारित करने के लिए, हमने तीन मुख्य विशेषताओं की पहचान की।

1. यह पूरा होना चाहिए। यह बहुत सुंदर लगता है, लेकिन यह ध्यान रखना महत्वपूर्ण है। इसे कार्यान्वित समाधान के सभी तत्वों का विस्तार से वर्णन करना चाहिए।
2. यह प्रासंगिक होना चाहिए। यही है, समाधान के वर्तमान कार्यान्वयन के अनुरूप है।
3. यह स्पष्ट होना चाहिए। ताकि इसका उपयोग करने वाला व्यक्ति यह समझे कि समाधान कैसे लागू किया जाता है।

संक्षेप - पूर्ण, प्रासंगिक और समझने योग्य प्रलेखन।

साक्षात्कार

प्रलेखन की गुणवत्ता का आकलन करने के लिए, हमने उन लोगों के साक्षात्कार का निर्णय लिया जो सीधे इसके साथ काम करते हैं: एनआईबी विश्लेषक। उत्तरदाताओं को योजना के अनुसार 10 बयानों को रेट करने के लिए कहा गया था "1 से 5 के पैमाने पर (पूरी तरह से असहमत - पूरी तरह से सहमत)"।

आरोपों ने गुणवत्ता दस्तावेजों की विशेषताओं और एनआईबी दस्तावेजों के बारे में सर्वेक्षण के संकलक की राय को प्रतिबिंबित किया।

1. एनआईबी अनुप्रयोगों पर प्रलेखन प्रासंगिक और पूरी तरह से उनके कार्यान्वयन के अनुरूप है।
2. एनआईबी अनुप्रयोगों का कार्यान्वयन पूरी तरह से प्रलेखित है।
3. एनआईबी अनुप्रयोगों पर प्रलेखन केवल कार्यात्मक समर्थन के लिए आवश्यक है।
4. एनआईबी अनुप्रयोगों पर प्रलेखन कार्यात्मक समर्थन के लिए उनके प्रस्तुत करने के समय प्रासंगिक है।
5. एनआईबी एप्लिकेशन डेवलपर्स यह समझने के लिए दस्तावेज़ीकरण का उपयोग करते हैं कि उन्हें क्या लागू करना है।
6. एनआईबी अनुप्रयोगों के लिए प्रलेखन यह समझने के लिए पर्याप्त है कि उन्हें कैसे लागू किया जाता है।
7. यदि वे अंतिम रूप से (मेरी टीम द्वारा) एनआईबी परियोजनाओं पर समयबद्ध तरीके से प्रलेखन अद्यतन करेंगे।
8. NIB एप्लिकेशन डेवलपर्स दस्तावेज़ीकरण की समीक्षा करते हैं।
9. मुझे एनआईबी परियोजनाओं का दस्तावेजीकरण करने की स्पष्ट समझ है।
10. मैं समझता हूं कि एनआईबी परियोजनाओं पर प्रलेखन कब लिखना / अपडेट करना है।

यह स्पष्ट है कि बस उत्तर "1 से 5" आवश्यक विवरण प्रकट नहीं कर सकता है, इसलिए एक व्यक्ति प्रत्येक आइटम पर एक टिप्पणी छोड़ सकता है।

हमने कॉरपोरेट स्लैक के माध्यम से यह सब किया - हमने सिस्टम विश्लेषकों को सर्वेक्षण लेने के लिए एक प्रस्ताव भेजा। 15 विश्लेषक (मास्को से 9 और सेंट पीटर्सबर्ग से 6) थे। सर्वेक्षण पूरा होने के बाद, हमने प्रत्येक 10 बयानों के लिए औसत रेटिंग बनाई, जो तब सामान्यीकृत थी।

यही हुआ है।



सर्वेक्षण से पता चला कि हालांकि विश्लेषकों का मानना ​​है कि एनआईबी अनुप्रयोगों के कार्यान्वयन को पूरी तरह से प्रलेखित किया गया है, वे असंदिग्ध समझौते (0.2) नहीं देते हैं। एक ठोस उदाहरण के रूप में, उन्होंने संकेत दिया कि कई डेटाबेस और मौजूदा समाधानों की कतारें प्रलेखन द्वारा कवर नहीं की गई थीं। डेवलपर विश्लेषक को यह बताने में सक्षम है कि सब कुछ प्रलेखित नहीं है। लेकिन डेवलपर्स ने प्रलेखन की समीक्षा की थीसिस को भी अस्पष्ट समर्थन (0.33) नहीं मिला। यही है, कार्यान्वित समाधानों के अपूर्ण विवरण का जोखिम बना हुआ है।

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

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

एनआईबी अनुप्रयोगों पर प्रलेखन कार्यात्मक समर्थन (0.73) के लिए वितरण के समय प्रासंगिक है। यह समझ में आता है, क्योंकि एक परियोजना को कार्यात्मक समर्थन देने के लिए मानदंडों में से एक अप-टू-डेट प्रलेखन है। यह कार्यान्वयन (0.67) को समझने के लिए भी पर्याप्त है, हालांकि कभी-कभी प्रश्न बने रहते हैं।

लेकिन जो उत्तरदाता इससे सहमत नहीं थे (बल्कि सर्वसम्मति से) यह है कि एनआईबी अनुप्रयोगों पर प्रलेखन, सिद्धांत रूप में, केवल कार्यात्मक समर्थन (-1.53) के लिए आवश्यक है। प्रलेखन के उपभोक्ताओं के रूप में विश्लेषकों को सबसे अधिक बार उल्लेख किया गया था। शेष टीम के सदस्य (डेवलपर्स) - बहुत कम बार। इसके अलावा, विश्लेषकों का मानना ​​है कि डेवलपर्स यह समझने के लिए प्रलेखन का उपयोग नहीं करते हैं कि उन्हें क्या लागू करने की आवश्यकता है, हालांकि एकमत नहीं (-0.06)। वैसे, यह उन परिस्थितियों में भी अपेक्षित है जब कोड विकास और लेखन प्रलेखन समानांतर में चलते हैं।

परिणाम क्या है और हमें इन नंबरों की आवश्यकता क्यों है

दस्तावेजों की गुणवत्ता में सुधार करने के लिए, हमने ऐसा करने का फैसला किया:

1. डेवलपर को लिखित दस्तावेजों की समीक्षा करने के लिए कहें।
2. यदि संभव हो, तो दस्तावेज़ीकरण को समय पर अपडेट करें, सामने - पहले स्थान पर।
3. एनआईबी परियोजनाओं के दस्तावेज़ीकरण के लिए एक मानक बनाएं और अपनाएं ताकि हर कोई जल्दी से समझ सके कि सिस्टम के कौन से तत्व हैं और इसका वर्णन कैसे करें। खैर, उपयुक्त टेम्पलेट विकसित करें।

यह सब दस्तावेजों की गुणवत्ता को एक नए स्तर तक बढ़ाने में मदद करना चाहिए।

कम से कम मुझे उम्मीद है।