डेटा और एनालिटिक्स में दस्तावेज़ीकरण

Jun 17 2022

दस्तावेज़ीकरण कुछ ऐसा है जिसे IMO बहुत गलत समझा जाता है। ये विषय पर मेरे मैक्रो-स्तरीय वैचारिक विचार हैं (डेटा और उससे आगे पर लागू होता है) इसका उद्देश्य: संदर्भ और स्पष्टता अधिक विवरण में, आप यह सुनिश्चित करना चाहते हैं कि भविष्य के पाठक / उपयोगकर्ता ( मॉडल/रूपांतरण/क्वेरी/कोड/आदि के मॉडल/रूपांतरण/क्वेरी/कोड/आदि के बारे में समझेंगे कि आपके पास वापस आने की आवश्यकता के बिना क्या किया गया है और आपसे आपके द्वारा किए गए काम के बारे में और क्यों पूछा गया है।

दस्तावेज़ीकरण ऐसा कुछ है जिसे बहुत सी आईएमओ गलत समझा जाता है।
विषय पर ये मेरे मैक्रो-स्तरीय वैचारिक विचार हैं (डेटा और उससे आगे पर लागू होता है)

इसका उद्देश्य: संदर्भ और स्पष्टता

अधिक विवरण में, आप यह सुनिश्चित करना चाहते हैं कि मॉडल/रूपांतरण/क्वेरी/कोड/आदि के भविष्य के पाठक/उपयोगकर्ता (स्वयं शामिल!) समझेंगे कि आपके पास वापस आने और आपसे पूछे बिना क्या किया गया है काम तुमने किया और क्यों किया।

यह स्वाद है: अधिक विविध कि हम क्या सोच सकते हैं

उनमें से कुछ जिन्हें मैं सचेत रूप से मानता हूं:

तुम्हारा कोड!!! यहीं से सब कुछ शुरू होता है। अंतिम लक्ष्य स्पष्टता है, चतुर कोड या मॉडल न लिखें, कुछ ऐसा लिखें जिसे हर कोई समझ सके। आपका कोड स्वयं दस्तावेज़ होना चाहिए
नामकरण: यह मूल रूप से पहले बिंदु का एक परिणाम है, क्योंकि आपके कोड में तर्क है जो इसे लागू करता है और भाषा/शब्द/नामकरण इसे मानव पाठक को आसानी से व्यक्त करने के लिए है। सहायक सहज नामकरण (फ़ाइलों, डेटासेट, डेटा मॉडल, कॉलम…) के लिए। नाम जैसे tmp, tmp_1, test_data, आदि... निश्चित रूप से एक बुरा अभ्यास है। यदि आप उनका उपयोग कर रहे हैं, तो सुनिश्चित करें कि वे कभी भी बाहरी दुनिया के संपर्क में न आएं! गंभीरता से…
टिप्पणियाँ: यदि कोड (तर्क और नामकरण) पर्याप्त नहीं है - उदाहरण के लिए अधिक जटिल उपयोग के मामलों के लिए जिसमें ऐतिहासिक संदर्भ जोड़ने और कुछ बाहरी दस्तावेज़ों को इंगित करने की आवश्यकता होती है-, कोड में अतिरिक्त टिप्पणियों की अत्यधिक अनुशंसा की जाती है। अगले डेवलपर/पाठक का ध्यान भंग होने से बचाने के लिए, इसे संक्षिप्त, स्पष्ट और निश्चित रूप से भ्रमित न करने का ध्यान रखें। भ्रामक/भ्रामक से बेहतर कोई दस्तावेज नहीं है
ToDos: ToDos कोड है, मूल रूप से एक टिप्पणी ++ (एक टिप्पणी जो भविष्य की कार्रवाई के लिए कॉल करती है) की तरह है। उदाहरण के लिए टेकडेट को स्मार्ट तरीके से प्रबंधित करने के लिए इसे रणनीतिक रूप से उपयोग करें: यदि आप देखते हैं कि कुछ पुराने टुकड़ों के लिए रिफैक्टरिंग की आवश्यकता है और वर्तमान परियोजना के लिए आपकी समय सीमा आपको इसे स्वयं से निपटने नहीं देगी, तो निश्चित रूप से एक टूडू (संदर्भ के साथ) जोड़ें। अगला पाठक इस पर फिर से विचार करेगा और तय करेगा कि क्या करना है। वह जिम्मेदार सहयोगी विकास है!
परीक्षण: परीक्षण उपयोगकर्ता/पाठक को मॉडल की संरचना और उसके द्वारा संसाधित किए जाने वाले डेटा को समझने में मदद करता है। एक उदाहरण: डेटा परीक्षणों में विशिष्टता परीक्षण डेटा की ग्रैन्युलैरिटी को समझने में मदद करता है ( डीबीटी परीक्षण पढ़ते समय मैं सबसे पहले जांचता हूं।
कोडबेस में दस्तावेज़ीकरण (आवश्यकतानुसार): लगभग सभी भाषाएं जो 'आत्म-सम्मान' पारंपरिक तरीके प्रदान करती हैं कि कैसे आपके कोड को व्यवस्थित रूप से दस्तावेज किया जाए। डीबीटी के लिए, आपके द्वारा बनाए जा रहे मॉडल (एसक्यूएल) से जुड़ी एक वाईएमएल फाइल वह जगह है जहां आप यह कर सकते हैं। उदाहरण के लिए पायथन डॉकस्ट्रिंग प्रदान करता है । इसका भी अच्छे से इस्तेमाल करें। इसका उपयोग कोड में टिप्पणियों के संयोजन के साथ किया जाना चाहिए। दोनों के बीच सही संतुलन एक ऐसी कला है जो अभ्यास से निखरती जाती है
कोडबेस के बाहर दस्तावेज़ीकरण (जैसे संगम पर): अधिकतर अधिक जटिल प्रासंगिक विषयों के लिए जैसे कि एमएल मॉडल के व्यावसायिक उपयोग के मामले का दस्तावेजीकरण, पाइपलाइन, आर्किटेक्चर, जटिल डेटा स्रोत, आदि की रिपोर्ट करना… मेरी टीम को द फैबुलस से संबंधित कुछ भी दस्तावेज करने की मेरी सिफारिश है कोड (इसके चारों ओर ठोस तर्क) कोड के करीब, और संगम पर व्यवसाय (कार्यात्मक प्रलेखन) के करीब कुछ भी

क्या मैं जो कुछ बना रहा हूं उससे अगला पाठक संघर्ष का सामना करेगा?'

यदि उत्तर हाँ है, तो आगे सरल करें और दस्तावेज़ को बेहतर बनाएं!