उद्योग में प्रलेखन के लिए क्या है?

Question

लगता है कि यहां तक ​​कि सबसे बुनियादी दस्तावेज लिखने का भी विरोध हो रहा है। हमारी परियोजना READMEs अपेक्षाकृत नंगे हैं। डॉक्स में निर्भरता की अद्यतन सूची भी नहीं है।

क्या ऐसा कुछ है जो मैं उद्योग में अनभिज्ञ हूँ, जो प्रोग्रामर को लेखन दस्तावेज नापसंद करता है? यदि आवश्यक हो, तो मैं डॉक्स के पैराग्राफ टाइप कर सकता हूं, तो अन्य लोग इसके विपरीत क्यों हैं?

इससे भी महत्वपूर्ण बात, मैं उन्हें कैसे समझाऊं कि डॉक्स लिखने से हमें भविष्य में समय और निराशा से बचा जा सकेगा?

Comments

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

— Ampt

क्योंकि अनुभव ने साबित कर दिया है कि कोई भी डॉक्स नहीं पढ़ता है।

— user16764

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

— पैट्रिक ह्यूजेस

डॉक्स को नवीनतम कोड के साथ रखना "चुनौतीपूर्ण" हो सकता है, यदि आप जावदोक या समकक्ष से उच्च स्तर पर लिख रहे हैं।

— डेन पिकेलमैन

यह मजेदार नहीं है ...

Answer 1

मुझे नहीं लगता कि यह उन लोगों की प्रेरणाओं पर अटकल लगाने में मददगार है, जो आपके विचार से कुछ अच्छा तरीका नहीं अपना रहे हैं या जो आपके द्वारा बुरे अभ्यास के रूप में कुछ कर रहे हैं। इस व्यवसाय में, जो लोग एक या दोनों श्रेणियों में आते हैं, वे उन लोगों से दूर हो जाएंगे , जिनके साथ आप आंखें मिलाकर देखेंगे, इसलिए खुद को पागल बनाना बंद कर दें।

इसके बजाय, समस्या और संभावित प्रस्तावों पर ध्यान केंद्रित करें।

1. अच्छा डॉक्यूमेंटेशन खुद लिखें

यह उम्मीद करना यथार्थवादी नहीं हो सकता है कि आपकी टीम के सभी लोग आपके प्रयासों को एक समस्या के रूप में देखेंगे। यह विशेष रूप से सच है यदि आप टीम के लिए एक नए नवागंतुक हैं। मैं यह अनुमान लगाने के लिए उद्यम करूंगा कि आप हैं, क्योंकि यदि आप टीम के संस्थापक सदस्य थे, तो ऐसा लगता है कि आप इस मुद्दे को पहले ही हल कर चुके हैं।

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

यदि कोई मुझसे पूछता है कि क्लाइंट सी के लिए किसी चीज़ को कस्टमाइज़ करने के लिए फ़ैक्टरी एफ के नए कार्यान्वयन को कैसे लिखा जाए, तो मैं उन्हें बताता हूं कि यह डेवलपर गाइड के पेज 10 पर है।

अधिकांश डेवलपर्स ऐसे प्रश्न पूछने से नफरत करते हैं, जो उन्हें ऐसा दिखा सकते हैं जैसे कि वे दस्तावेजीकरण से नफरत करने की तुलना में "कोड को पढ़ नहीं सकते" उससे भी अधिक, इसलिए इस प्रकृति के पर्याप्त उत्तरों के बाद, वे पहले डॉक्स पर जाएंगे।

2. अपने दस्तावेज़ का मूल्य साबित करें

सुनिश्चित करें कि आप यह इंगित करने के लिए हर अवसर लेते हैं कि दस्तावेज़ीकरण इसका मूल्य कैसे साबित कर रहा है (या यदि उपयोग किया जाता है)। सूक्ष्म होने की कोशिश करें और "मैंने आपको ऐसा कहा था," से बचने के लिए, लेकिन चीजों को कहने के लिए पूरी तरह से वैध है

भविष्य के संदर्भ के लिए, इस परियोजना के विकी पृष्ठ में कोर कोड की शाखा के बारे में जानकारी है जो रिलीज़ 2.1 के चल रहे समर्थन के लिए बनाई गई थी, इसलिए भविष्य में हम एक पूर्ण प्रतिगमन परीक्षण करने से बच सकते हैं यदि वे लोग जो रिलीज़ किए गए संस्करणों की जांच कर रहे हैं कोड की जाँच करने से पहले विकी।

या

मुझे खुशी है कि मैंने टास्क टी करने के लिए चरणों को लिखा। मुझे वास्तव में परवाह नहीं है अगर कोई और कभी भी इसका उपयोग नहीं करता है - यह पहले से ही अधिक समय बचा रहा है जितना मैंने इसे लिखने में खर्च किया है।

3. बोर्ड पर प्रबंधन प्राप्त करें

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

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

4. जब आप इसे देखते हैं तो प्रलेखन को प्रोत्साहित करें

हो सकता है कि इस कारण से लोग अक्सर डॉक्स नहीं लिखते हैं क्योंकि उन्हें लगता है कि उन्हें लगता है कि कोई भी इसे नहीं पढ़ रहा है। इसलिए, जब आप अपनी पसंद की कोई चीज़ देखते हैं, तो कम से कम यह उल्लेख करना सुनिश्चित करें कि आपको खुशी है कि यह उपलब्ध था।

यदि आपकी टीम कोड की समीक्षा करती है, तो यह एक ऐसा समय है जब आप अच्छी टिप्पणियों को प्रोत्साहित करने के लिए सूक्ष्म शब्द या दो में छोड़ सकते हैं।

फ्रेमवर्क जी में बग बी के लिए वर्कअराउंड का दस्तावेजीकरण करने के लिए धन्यवाद। मुझे इसके बारे में पता नहीं था, और मुझे नहीं लगता कि मैं समझ सकता था कि आप इसके बिना क्या कर रहे थे।

यदि आपके पास टीम में कोई है जो वास्तव में प्रलेखन के बारे में उत्साही है, तो यह उस व्यक्ति को दोपहर के भोजन या कॉफी पर जाने के माध्यम से खेती करने के लिए चोट नहीं पहुंचाता है और बाकी टीम को देखने से प्राप्त होने वाले हतोत्साहन का मुकाबला करने के लिए थोड़ा सत्यापन करने की पेशकश करना सुनिश्चित करता है प्रलेखन को उतना महत्व नहीं देता।

इसके अलावा, यह वास्तव में आपकी समस्या नहीं है जब तक कि आप लीड या प्रबंधन की स्थिति में न हों। आप पानी के लिए एक घोड़े का नेतृत्व कर सकते हैं, लेकिन आप इसे पी नहीं सकते। यदि यह आपका घोड़ा नहीं है, तो आप खुश नहीं हो सकते हैं कि यह प्यासा है, लेकिन आप जो कुछ भी कर सकते हैं वह गर्त को भरना है।

Comments

प्वाइंट # 2 के लिए +1, सीधे ओपी के प्रश्न का उत्तर देना जो "मैं कैसे

— मनाऊं

मुझे यह उत्तर पसंद है, अन्य लोगों ने "क्यों" के बजाय "क्यों" पर अधिक ध्यान केंद्रित किया

— रुडोल्फ ओला

@omouse - ऐसा इसलिए है क्योंकि अधिकांश मामलों के लिए, दस्तावेज़ लिखना आपको भविष्य में समय और हताशा से नहीं बचाएगा। वे शायद ही कभी सटीक होते हैं, और लोग कभी भी उन्हें पढ़ते नहीं हैं।

— तेलस्टीन

ठोस सिद्धांत आमतौर पर आपका समय या परिणाम बेहतर डिजाइन में नहीं बचाते हैं, या तो, क्योंकि ज्यादातर लोग या तो उन्हें पूरी तरह से समझते नहीं हैं या वास्तव में बकवास नहीं करते हैं। आपके तर्क से, हमें उन्हें, GRASP, या किसी भी अन्य अच्छी प्रथाओं को लागू करने की इच्छा नहीं करनी चाहिए। मुझे याद दिलाएं कि आप प्रोग्रामर में फिर से भाग लेने के लिए क्यों परेशान हैं?

— एमी ब्लेंकशिप

यह लोगों की प्रेरणाओं पर अटकलें लगाने में बहुत मददगार लगता है।

— tymtam

Answer 2

मेरे अनुभव में दो मुख्य कारक हैं:

समय सीमा

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

परिवर्तन

डेवलपर्स के लिए एक अपेक्षाकृत नया सबसे अच्छा अभ्यास टिप्पणियों पर डे-जोर देना है। विचार यह है कि दो स्थानों (कोड [परीक्षणों सहित] और कोड के आसपास की टिप्पणियां) में जानकारी रखने से उन्हें बहुत कम लाभ के लिए सिंक में रखने के लिए बहुत अधिक ओवरहेड हो जाता है। "यदि आपका कोड पढ़ने में इतना कठिन है कि आपको टिप्पणियों की आवश्यकता है, तो क्या कोड को साफ करने में बेहतर समय नहीं लगेगा?"

मैं व्यक्तिगत रूप से किसी भी टिप्पणी पर ध्यान नहीं देंगे। कोड झूठ नहीं बोल सकता।

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

Comments

+1 के लिए "मैं व्यक्तिगत रूप से किसी भी टिप्पणी को नहीं देखूंगा", मुझे लगता है कि यह आम है; जब आप कोड के साथ एक निश्चित आराम स्तर तक बढ़ते हैं, तो आप इसे टिप्पणियों की तुलना में जल्दी पढ़ सकते हैं (और अभी भी अगर टिप्पणी रास्ते में नहीं हैं), और कोड झूठ नहीं बोलता है

— जिमी हॉफ

यह टिप्पणियों के बिंदु को याद करता है, जो यह समझाने के लिए है कि क्यों । उन्हें सभी जगह होने की आवश्यकता नहीं है, और उन्हें बहुत लंबे समय तक रहने की आवश्यकता नहीं है, लेकिन व्यापारिक नियमों के लिए एक अच्छी तरह से रखा गया लिंक बताता है कि इसकी वर्तमान स्थिति में वास्तव में विचित्र तर्क की अगली 20 लाइनें मौजूद क्यों हैं? मूल तर्क खोजने के लिए संस्करण इतिहास के माध्यम से स्लॉग करने की कोशिश करना सुविधाजनक है।

— zzzzBov

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

— तेलस्टिन

कोड झूठ बोल सकते हैं। हो सकता है कि ग्राहक कुछ चाहता था, और उसे कुछ और करने के लिए कोडित किया गया था। तो अगर आप सब अब कोड है, यह सही है?

— thursdaysgeek

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

— केविन रुबिन

Answer 3

यहाँ खेलने में कई कारक हैं:

1. अच्छी तरह से लिखा कोड अपने स्वयं के प्रलेखन है। अन्य सभी चीजें समान होने के कारण, क्लियर कोड लिखना बेहतर है जो अधिक प्रलेखन के बजाय स्वयं के लिए बोलता है। जब आप उस कोड को बदलते हैं, तो आपको कम प्रलेखन को संशोधित करने की आवश्यकता होगी।

2. कोड लिखने की तुलना में लेखन दस्तावेज़ यकीनन एक अलग कौशल है। कुछ सॉफ्टवेयर डेवलपर्स दूसरों की तुलना में इस पर बेहतर हैं। कुछ लेखन कोड में बहुत बेहतर है, क्योंकि वे प्रलेखन लिख रहे हैं।

3. दस्तावेज़ीकरण केवल एक बार लिखा जाना चाहिए , दो बार (स्रोत कोड में एक बार, और फिर से प्रोग्रामर के गाइड में)। इसलिए हमारे पास XML कमेंट्स और डॉक्यूमेंटेशन जनरेटर जैसी चीजें हैं। दुर्भाग्य से, ऐसे उपकरण का उपयोग करना केवल हाथ से प्रलेखन लिखने से अधिक मुश्किल और बोझिल हो सकता है, यही कारण है कि आप उन उपकरणों को व्यापक रूप से उपयोग नहीं करते हैं।

4. अच्छा प्रलेखन समय लेने वाला है, और अच्छा करने के लिए कठिन है। अन्य सभी चीजें समान होने के कारण, पहले से मौजूद कोड के लिए दस्तावेज़ लिखने की तुलना में नया कोड लिखने के लिए अधिक मूल्य हो सकता है।

5. जब कोड बदलता है, तो आपको दस्तावेज़ भी बदलना होगा। कम प्रलेखन वहाँ है, कम है कि बदलना होगा।

6. कोई भी किसी भी तरह से प्रलेखन नहीं पढ़ता है, इसलिए परेशान क्यों है?

Comments

# 1 फिर से, मुझे नहीं लगता कि ऐसा कभी होता है, लेकिन # 4 निश्चित रूप से सच है

— रुडोल्फ ओला

@whatsisname: बिलकुल नहीं। क्लियर कोड लिखिए जिसके लिए कम डॉक्यूमेंटेशन की आवश्यकता होती है, और जब आप उस कोड को बदलते हैं तो आपको कम डॉक्यूमेंट को संशोधित करना होगा।

— रॉबर्ट हार्वे

@thursdaysgeek: उन गोलियों का क्या मतलब है कि आपको दस्तावेज़ को दो बार लिखना नहीं चाहिए: एक बार कोड टिप्पणियों के लिए, और फिर से मदद फ़ाइल / प्रोग्रामर संदर्भ के लिए। आपको निश्चित रूप से इसे दो बार फिर से लिखना नहीं चाहिए । क्या तुम लोग इस बात को पढ़ रहे हो?

— रॉबर्ट हार्वे

# 6 ... मुझे लगता है कि यह एक सामान्य गलत धारणा है। एक बहुत से लोगों को अच्छी तरह से दस्तावेज़ पढ़ें।

— डायनामिक

@tymek: आपको अपना साइन पीछे की ओर मिला। दोस्तों, यह प्रलेखन बनाने के तरीके के बारे में एक ट्यूटोरियल नहीं है; यह डेवलपर्स के प्रति नकारात्मक रवैया क्यों है, इस बात की प्रतिध्वनि है।

— रॉबर्ट हार्वे

Answer 4

कमरे में हाथी: प्रोग्रामर (आवश्यक) लेखक नहीं हैं। न ही वे आवश्यक रूप से तकनीकी लेखकों के लिए अपने कार्यान्वयन को दूर करने के लिए उत्तरदायी हैं। कमरे में दूसरा हाथी: तकनीकी लेखक आमतौर पर भविष्य के डेवलपर्स के लिए उपयोगी विवरणों को बाहर करने में सक्षम नहीं होते हैं (भले ही डेवलपर्स उन्हें समझाने के लिए काम करेंगे)।

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

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

ऐसा कभी नहीं होगा।

Comments

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

— जानिए

मेरा सुझाव है कि "सीमित (सीमित) प्रलेखन के साथ अपने इरादों के संचार की मूल क्षमता" आवश्यक प्रोग्रामर कौशल है। एक प्रोग्रामर को कवि होने की ज़रूरत नहीं है, लेकिन अगर वह दस्तावेज नहीं दे सकता है, तो मैं ईमानदारी से उसे अपनी टीम में नहीं लेना चाहता। ऐसा व्यक्ति एक दीर्घकालिक देयता है।

Answer 5

इससे भी महत्वपूर्ण बात, मैं उन्हें कैसे समझाऊं कि डॉक्स लिखने से हमें भविष्य में समय और निराशा से बचा जा सकेगा?

क्या वह ऐसा करता है?

प्रलेखन के दो प्रकार हैं:

उपयोगी दस्तावेज

दस्तावेज तैयार उत्पाद का उपयोग कैसे करें, एक एपीआई, जो आईपी या हमारे सर्वर के URL का नाम है, आदि, मूल रूप से, वह सब कुछ जो भारी और दैनिक आधार पर उपयोग किया जाता है। गलत जानकारी जल्दी से मिल जाएगी और सही हो जाएगी। आसानी से और आसानी से संपादित करने की आवश्यकता है (जैसे ऑनलाइन विकी)।

बेकार दस्तावेज

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

प्रोग्रामर बेकार दस्तावेज लिखना या पढ़ना पसंद नहीं करते हैं। लेकिन अगर आप उन्हें प्रलेखन दिखा सकते हैं जो उपयोगी है, तो वे इसे लिखेंगे। विकी को पेश करने के दौरान हमें अपनी आखिरी परियोजना में सफलता मिली थी, जहां हम अपनी जरूरत की सभी जानकारी अक्सर लिख सकते थे।

Answer 6

मैं कहूंगा कि मुख्य कारण इच्छाशक्ति की कमी और प्रलेखन के कार्य की समझ की कमी है। विचार करने के लिए प्रलेखन की कई कक्षाएं हैं:

उत्पाद / रिलीज प्रलेखन

यह कुछ भी है जो आपके 'समाप्त' उत्पाद के साथ निकलता है। यह केवल मैनुअल से अधिक है, यह READMEs, चेंज लॉग्स, HOW-TOs और पसंद है। सिद्धांत रूप में, आप इन्हें नहीं लिखने के साथ दूर हो सकते हैं, लेकिन आप एक ऐसे उत्पाद के साथ समाप्त होते हैं, जिसे लोग उपयोग नहीं करना चाहते हैं, या एक समर्थन बोझ जो अनावश्यक रूप से महंगा है।

एपीआई प्रलेखन

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

कोड टिप्पणियाँ

टिप्पणियों पर उद्योग की राय फिलहाल प्रवाह में है। जब मैंने पहली बार पेशेवर रूप से कोडिंग शुरू की थी, तो जब यह कोड लिखने की बात आती थी तो टिप्पणियाँ एक साइन क्वालिफिकेशन नॉन थीं । अब, फैशन कोड लिखना है जो इतना स्पष्ट है, टिप्पणियां अनावश्यक हैं। मुझे लगता है कि यह अनुमान है कि यह आंशिक रूप से है, इस तथ्य के कारण कि कई आधुनिक भाषाएं बहुत उच्च स्तर पर लिखी गई हैं और जावा, जावास्क्रिप्ट, रूबी आदि में सुगम कोड लिखना आसान है, क्योंकि यह कोडांतरक में था , C, FORTRAN, आदि इस प्रकार, टिप्पणियों का अधिक मूल्य था।

मेरा अब भी मानना ​​है कि उन टिप्पणियों में मूल्य होता है जो कोड के एक भाग के इरादे का वर्णन करते हैं , या कुछ विवरणों के बारे में क्यों कि एक निश्चित एल्गोरिथ्म को अधिक स्पष्ट रूप से चुना गया था (ओवर फिक्सिंग से बचने के लिए 'फिक्सिंग' कोड से फिक्सेशन होता है जो doesn ' टी वास्तव में तय की जरूरत है)।

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

Comments

+1 "प्रलेखन के लिए प्राथमिक दर्शक अन्य लोग हैं"। बहुत से प्रोग्रामर वास्तव में दूसरों के साथ संवाद करने के लिए महत्व नहीं देते हैं। (यही कारण है कि वे वरिष्ठता में आगे बढ़ना मुश्किल पाएंगे।)

— डोनल फैलो

Answer 7

यहाँ मेरे दो सेंट हैं।

1. एजाइल मेनिफेस्टो में कहा गया है, "व्यापक प्रलेखन पर कार्यशील सॉफ़्टवेयर" और हर कोई इस तक पहुंचने के लिए नहीं पढ़ता है "यही है, जबकि दाईं ओर की वस्तुओं में मूल्य है, हम बाईं ओर की वस्तुओं को अधिक महत्व देते हैं।"

2. अफसोस की बात है कि यह https://en.wikipedia.org/wiki/Code_and_fix के लिए सामान्य है और प्रलेखन इस मॉडल के साथ काम नहीं करता है (यह सिंक से बाहर हो जाता है)।

3. सॉफ्टवेयर विकास उद्योग अच्छी तरह से विनियमित नहीं है। प्रलेखन लिखने के लिए कोई कानूनी आवश्यकता नहीं है।

4. सेल्फ-डॉक्यूमेंटिंग कोड वर्तमान प्रवृत्ति है।

ऐसा कहने के बाद, मुझे लगता है कि वहाँ बहुत सारे अच्छे दस्तावेज हैं।

Comments

(१) " हम बाईं ओर की चीजों को अधिक महत्व देते हैं ... " का अर्थ यह नहीं है कि हम दाईं ओर की परवाह नहीं करते हैं। (२) " ४.साल-दस्तावेज कोड वर्तमान प्रवृत्ति है " यदि प्रलेखन आवश्यक नहीं है, तो यह क्यों है कि लोग सबसे पहले और सबसे खराब प्रलेखन के बारे में शिकायत करते हैं? (३) जिस समय एक डेवलपर अपने काम का दस्तावेजीकरण न करके बचत करता है, उसे हर एक डेवलपर द्वारा खर्च किया जाता है , जिसे सूचना की आवश्यकता होती है, क्योंकि उसे ५ पन्नों के दस्तावेज के बजाय स्व-दस्तावेजीकरण कोड की ५००० लाइनों को स्कैन करना होता है। दक्षता कुछ और है, लेकिन हे, हम फुर्तीले हैं!

— जेन्सजी

Answer 8

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

किसी भी आधे-सभ्य दस्तावेज का भविष्य में निवेश होता है। यदि आप भविष्य के बारे में परवाह नहीं करते हैं (क्योंकि आप अगले पेचेक से परे नहीं सोचते हैं, या क्योंकि आपको लगता है कि यह आपकी समस्या नहीं होगी), तो प्रलेखन करने का विचार बेहद दर्दनाक है।

Answer 9

कई अन्य प्रतिक्रियाएं इस बात पर चमकती हैं कि कम से कम दो प्रकार के प्रलेखन हैं: अन्य डेवलपर्स के लिए एक सेट, और अंतिम उपयोगकर्ताओं के लिए एक अलग सेट। आपके वातावरण के आधार पर, आपको सिस्टम एडमिनिस्ट्रेटर, इंस्टॉलर और हेल्प डेस्क कर्मियों के लिए अतिरिक्त प्रलेखन की भी आवश्यकता हो सकती है। प्रत्येक लक्षित दर्शकों की समझ की विभिन्न आवश्यकताएं और स्तर हैं।

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

एक अच्छा प्रलेखन लेखक कई भाषाओं में संवाद कर सकता है: उपयोगकर्ताओं की भाषा, प्रबंधन की भाषा, सहायक कर्मचारियों की भाषा, डेवलपर्स की भाषा। यह एक प्रलेखन लेखक का काम है कि एक कोडर क्या संचार करता है और उस रूप में अनुवाद करने के लिए जिसे अन्य सभी समूह समझ सकते हैं।

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

इस कारण से, प्रलेखन (इनलाइन कोड टिप्पणियों के अपवाद के साथ) संचारकों के लिए सबसे अच्छा बचा है, कोडर नहीं।

Comments

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

— एमी ब्लैंकेनशिप

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

— केविन रुबिन

Answer 10

कोड पढ़ना आपको दिखाता है कि यह कैसे काम करता है। यह नहीं समझा सकता है : आपको टिप्पणियों की आवश्यकता क्यों है ।

कोड पढ़ना आपको एक विधि का नाम, और मापदंडों के प्रकार दिखाता है। यह शब्दार्थ, या लेखक के सटीक इरादे की व्याख्या नहीं कर सकता: आपको टिप्पणियों की आवश्यकता है।

टिप्पणियाँ कोड पढ़ने की जगह नहीं लेती हैं, वे इसे जोड़ते हैं।

Comments

भावना के लिए +1। लेकिन यह सवाल का जवाब नहीं है; आप यहां पर वास्तविक प्रश्न के अलावा किसी और चीज का जवाब दे रहे हैं।

— bignose

Answer 11

कोड के रूप में प्रलेखन निष्पादित नहीं किया जाता है। नतीजतन, अक्सर प्रभावी फीडबैक लूप नहीं होते हैं यह सत्यापित करने के लिए कि दस्तावेज़ जगह में है और पूरा हो गया है। यही कारण है कि कोड टिप्पणियाँ सड़ने लगती हैं।

डोनाल्ड नुथ ने सॉफ्टवेयर की गुणवत्ता में सुधार करने के एक तरीके के रूप में लिटरेट प्रोग्रामिंग को बढ़ावा दिया , प्रभावी रूप से कोड के साथ दस्तावेज़ीकरण लिखा। मैंने कुछ परियोजनाएं देखी हैं, जिन्होंने इस दृष्टिकोण का काफी प्रभावी ढंग से उपयोग किया है।

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

Comments

स्वचालित पीढ़ी के प्रलेखन के लिए मेरी पसंद को सही ठहराने के लिए, मैं यह दिखाने के लिए एक नकली फार्मूला लेकर आया कि मानव जड़ता सभी टिप्पणी रोट का अपराधी कैसे है। तर्क पर विस्तार करते हुए, मैंने पाया कि स्रोत कोड में मेटा टिप्पणियों से आंशिक रूप से स्वचालित आरेख पीढ़ी की तरह, एक डेवलपर के लिए वास्तविक लाभ प्रदान करने वाले तरीकों का निर्माण, हर बार अपडेट होने की प्रवृत्ति होती है, एक डेवलपर कोड की समझ बनाने की कोशिश करता है। BTW, अधिक बार नहीं इस डेवलपर से सिर्फ "भविष्य मुझे" है।

— वोल्फमैनक्स

Answer 12

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

Answer 13

जो लोग डॉक्यूमेंटेशन पढ़ना पसंद करते हैं वे डॉक्यूमेंटेशन लिखना पसंद करते हैं। बहुत सारे प्रोग्रामर एक दस्तावेज़ को अच्छी तरह से पढ़ने से बचने के लिए वे सभी कर सकते हैं।

लेखन पर ध्यान केंद्रित न करें, पढ़ने पर ध्यान केंद्रित करें। जब प्रोग्रामर प्रलेखन पढ़ते हैं और इससे चीजों को आत्मसात करते हैं, तो वे मूल्य देखेंगे और कुछ लिखने के लिए अधिक इच्छुक होंगे।

Answer 14

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

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

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

हालाँकि

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

1. लोग आमतौर पर ईमेल की जांच करते हैं, जबकि कोई भी "डॉक्टर" नामक फ़ोल्डर के माध्यम से नहीं जाता है।

2. ईमेल संदर्भ में मौजूद है, जो अन्य ईमेलों से घिरा हुआ है जो इस फीचर और संबंधित सुविधाओं और उस समय चल रही किसी अन्य चीज पर चर्चा कर रहे हैं।

3. ईमेल छोटा और केंद्रित है और इसकी एक विषय पंक्ति है।

4. ईमेल उन लोगों को अनुमति देता है जो देखभाल करने के लिए तुरंत प्रश्न पूछते हैं,

5. ईमेल अत्यधिक खोज योग्य है, क्योंकि लोग इसका उपयोग हर चीज के लिए करते हैं और मेल क्लाइंट पिछले कुछ वर्षों में काफी उन्नत हुए हैं।

6. यदि यह ईमेल में है, तो कम से कम एक अन्य व्यक्ति जानता है कि इसे कहां खोजना है।

सिद्धांत रूप में यह प्रतीत होना चाहिए कि कोड में टिप्पणियां "आपके दिन के पहलू भी होनी चाहिए जो आप हमेशा वैसे भी करते हैं", लेकिन ईमानदार होने के लिए, मैंने कभी भी कोड में टिप्पणियों को नहीं पढ़ा। मुझे यकीन नहीं है कि क्यों, लेकिन वे सिर्फ बहुत मददगार नहीं हैं, शायद इसलिए कि संदर्भ की कमी है, जो ईमेल को हल करता है।

Comments

# 4 को छोड़कर ("जो लोग देखभाल करने वाले प्रश्नों को तुरंत पूछते हैं"), आपके द्वारा सूचीबद्ध ईमेल लाभों में से कोई भी मेरे लिए मज़बूती से काम नहीं कर रहा है। 1: लोग ईमेल को नजरअंदाज करते हैं, जब इसमें बहुत कुछ होता है 2: ईमेल अक्सर संदर्भ खोने के लिए जाता है, इसे साइड-इश्यू में दफन कर देता है और 3 को ओवरक्लोटिंग करता है : ईमेल बहुत अधिक लंबे / बड़े होते हैं और चर्चा के रूप में फोकस खो देते हैं। अधिक पक्ष के मुद्दे और विषय रेखाएं अक्सर अप्रासंगिक / अप्रचलित होती हैं ("Re: WTF आज सर्वर पर हुआ?") ...

— gnat

... 5: ईमेल खोज अत्यधिक मेल को नष्ट करने की क्षमता से समझौता किया जाता है, किसी भी सभ्य मेलर की सुविधा और किसी भी सक्रिय मेल उपयोगकर्ता को अच्छी तरह से, 6 का उपयोग करता है : 5 देखें, यदि मेल हटा दिया जाता है, तो कोई भी नहीं कर पाएगा इसे खोजें (केवल एक चीज जिस पर मैं भरोसा कर सकता हूं, वह मेरे भेजे गए मेल को खोज रही है और यह केवल इसलिए है क्योंकि मैं बहुत कोशिश करता हूं कि इन्हें हटाऊं नहीं)। ईमेल प्रशंसा के अलावा (जो मेरे लिए बहुत अनुचित लगती है), आप कुछ अच्छे बिंदु बनाते हैं

— gnat

@ मुझे लगता है कि इसे हटाने के बारे में कंपनी की कंपनी अलग-अलग हो सकती है। मेरी कंपनी में हम पिछले कर्मचारियों से सभी ईमेलों के साथ-साथ सभी ईमेलों को सहेजते हैं, और जब भी कोई नया काम शुरू होता है तो हम उस व्यक्ति को सभी संबंधित ईमेलों को अग्रेषित करते हैं। मुझे लगता है कि शैली में अंतर है।

— ओवेन

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

— gnat