महत्वपूर्ण : हमारे पास स्रोत कोड प्रलेखन के साथ कोई समस्या नहीं है । यह नियमित कोड ऑडिट के अंतर्गत आता है और इसे अद्यतित रखा जाता है। हमारी समस्या डेवलपर्स प्रलेखन (या, "बाहरी" यदि आपको पसंद है) के साथ है, तो प्रोग्रामर से प्रोग्रामर तक छोटे ब्लॉग जैसी युक्तियां जो एक बार लिखी जाती हैं, अक्सर पीछे रह जाती हैं।
हम प्रोग्रामर प्रलेखन का उत्पादन करने के लिए विकी जैसी प्रणाली का उपयोग करते हैं - प्रोग्रामर प्रोग्रामर द्वारा लिखे गए लेखों में थोड़ा और अधिक विवरण में वर्णन करते हैं कि कोड का विशेष टुकड़ा कैसे काम करता है। उन विकी पृष्ठों में आमतौर पर शामिल हैं:
- एपीआई के कुछ हिस्सों के लिए डिजाइन निर्णयों के पीछे प्रेरणा (उदाहरण के लिए; हमने यह बदसूरत काम किया क्योंकि यह विशेष रूप से 3 पार्टी लाइब्रेरी इस तरह से सामान करना चाहता है, क्योंकि यह अन्य पुस्तकालय ..., क्योंकि ...)
- इस बात की व्याख्या कि हम विशेष रूप से सामान्य कार्यों से कैसे निपटते हैं (उदाहरण के लिए, तुच्छ पॉपअप प्रदर्शित करना, जिसे उपयुक्त एप्लिकेशन शैलियों का संदर्भ देना है, रजिस्ट्री घटक में खुद को पंजीकृत करना है, और अन्य घटक द्वारा स्वचालित रूप से "स्कैन" होने के लिए कुछ इंटरफ़ेस लागू करना है)
- अच्छी प्रथाओं (व्यक्तिपरक के रूप में, हम वास्तव में इस सामान को लिखते हैं)
- पर्यावरण विन्यास, आवश्यक उपकरण और इसकी स्थापना
सामान्य तौर पर, मुख्य रूप से लेखन कोड से संबंधित सामान जो अपने आकार और ब्लॉग पोस्ट / लेख जैसी प्रकृति के कारण नियमित कोड-प्रलेखन में फिट नहीं होता है।
समस्या
जहाँ तक इस प्रणाली को पेश करने का कुछ महीने पहले एक अच्छा विचार था, आजकल मुझे ऐसा लगता है कि यह हल करने की तुलना में अधिक समस्याएं पैदा कर रहा है। उदाहरण के लिए:
- लोग कर लिखने लेख ... लेकिन एक बार कोड बदल गया है, विकी अद्यतन शायद ही कभी इस प्रकार है
- खरोंच के बहुत से लेख, किसी ने हड़बड़ी में लिखे और वैसे ही छोड़ दिए
- भले ही लेख-अनुरोध आमतौर पर परियोजना के नेतृत्व से आता है, यह शायद ही कभी शुद्धता / संरचना के लिए सत्यापित होता है - जिसके परिणामस्वरूप कभी-कभी खराब गुणवत्ता होती है
सामान्य गिरावट। कोड बदल गया, विकी वही रह गया। अगली बार जब कोई व्यक्ति जानकारी के लिए देखता है, तो वह जो पाता है वह पुराने, कम गुणवत्ता वाले सामान का गुच्छा होता है - और सोच रहा है कि क्या चल रहा है, क्या वह जो सामान मिला है वह सटीक है या (इससे भी बदतर) जो इसके कुछ हिस्से हैं। और जो मदद करने वाला था, वह उसके विपरीत काम करता है।
फिलहाल ऐसा लगता है कि लोग समस्या के बारे में जानते हैं, इसमें प्रोजेक्ट लीड शामिल है, लेकिन जाहिर तौर पर कोई भी इसके साथ कुछ भी करने के लिए परेशान नहीं दिखता है (या करने के लिए अधिक दिलचस्प सामान है)।
मेरा प्रारंभिक विचार यह सब गुमनामी में फेंकने का था (जब मैंने कई बार "पुरानी" युक्तियों से काट लिया), लेकिन मुझे लगता है कि यह बहुत चरम हो सकता है। कुछ जानकारी कभी-कभी ध्यान देने योग्य और अच्छी तरह से पढ़ने लायक होती है, लेकिन समस्या अभी भी वही है: आप इसके "अप-टू-डेटिटी" से कैसे निपटते हैं ? क्या यह स्रोत कोड से किसी भी तरह जुड़ा हुआ है (इसलिए जब फ़ाइल के अद्यतन संस्करण की जाँच की जाती है, तो लेख के लेखक को सूचित किया जाता है कि उसे कोड / लेख को संशोधित करने की आवश्यकता हो सकती है)? नामित व्यक्ति ने इसे दैनिक आधार पर "देख" लिया है? नियमित सफाई करें?