डेवलपर्स आपको दस्तावेज़ीकरण क्यों नहीं छोड़ना चाहिए

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

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

यद्यपि यह एक वास्तविक बोझ हो सकता है, लेकिन दस्तावेज लिखना महत्वपूर्ण है और यह आपके उपयोगकर्ताओं, आपके सहकर्मियों और स्वयं के लिए फायदे पहुंचाएगा.

अच्छा प्रलेखन उपयोगकर्ताओं की मदद करता है

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

उपयोगकर्ताओं के लिए इरादा प्रलेखन आमतौर पर व्यावहारिक उपयोग या शामिल हैं “कैसे”. सामान्य उपयोगकर्ताओं के लिए दस्तावेज़ बनाते समय अंगूठे का नियम है यह स्पष्ट होना चाहिए. मानव-अनुकूल शब्दों का उपयोग तकनीकी शब्दों या शब्दजाल के लिए बेहतर है। वास्तविक उपयोग के उदाहरणों की भी बहुत सराहना की जाएगी.

एक अच्छा लेआउट डिज़ाइन वास्तव में उपयोगकर्ताओं को आंखों के तनाव के बिना प्रलेखन के प्रत्येक अनुभाग के माध्यम से स्कैन करने में मदद करेगा। कुछ अच्छे उदाहरण (उर्फ मेरे पसंदीदा) बूटस्ट्रैप और वर्डप्रेस के लिए प्रलेखन हैं ' “वर्डप्रेस के साथ पहला कदम”.

यह अन्य डेवलपर्स को भी मदद करता है

प्रत्येक डेवलपर की अपनी स्वयं की कोडिंग शैली होगी। लेकिन, जब एक टीम में काम करने की बात आती है, तो हमें अक्सर दूसरी टीम के साथियों के साथ कोड साझा करना होगा। तो यह आवश्यक है एक मानक पर आम सहमति है सभी को एक ही पृष्ठ पर रखने के लिए। एक ठीक से लिखा प्रलेखन टीम की जरूरत है संदर्भ होगा

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

इसके अलावा, उस मामले में जहां आपके पास है नए सदस्य शामिल हो रहे हैं आपकी टीम बाद में, यह प्रलेखन उन्हें प्रशिक्षित करने का एक प्रभावी तरीका हो सकता है, इसलिए आपको उन्हें कोड पर 1-ऑन -1 रन देने की आवश्यकता नहीं है.

अजीब तरह से यह भी कोडर में मदद करता है

कोडिंग के बारे में मजेदार बात यह है कि कभी-कभी यहां तक ​​कि खुद डेवलपर्स भी उस कोड को नहीं समझते हैं जो उन्होंने लिखा है. यह उन मामलों में विशेष रूप से सच है जहां कोड महीनों या वर्षों तक अछूते रह गए हैं.

अचानक एक कारण या किसी अन्य के लिए कोड को फिर से देखने की जरूरत होती है, जब कोई सोचता है कि इन कोड को लिखने पर उनके दिमाग में क्या चल रहा है। हैरान न हों: मैं इस स्थिति में पहले भी रहा हूँ. ये है ठीक जब मैं कामना मैंने अपने कोड को ठीक से प्रलेखित किया था.

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

क्या अच्छा प्रलेखन के लिए बनाता है?

कई कारक हैं जो प्रलेखन का एक अच्छा टुकड़ा बनाने के लिए हैं.

1. कभी न मानें

यह मत समझो कि आपके उपयोगकर्ता जानते हैं कि क्या है आप साथ ही जानिए क्या वे जानना चाहता हूँ। यह हमेशा बेहतर होता है बहुत शुरुआत से शुरू करने के लिए उपयोगकर्ताओं की दक्षता स्तर की परवाह किए बिना.

यदि आपने एक jQuery प्लगइन बनाया है, उदाहरण के लिए, आप SlickJS के प्रलेखन से प्रेरणा ले सकते हैं। यह दिखाता है कि HTML को कैसे तैयार किया जाए, सीएसएस और जावास्क्रिप्ट को कहां रखा जाए, अपने सबसे बुनियादी स्तर पर jQuery प्लगइन को कैसे इनिशियलाइज़ किया जाए, और इन सभी सामानों को जोड़ने के बाद पूरा अंतिम मार्कअप भी दिखाया जाता है, जो कुछ स्पष्ट है.

लब्बोलुआब यह है कि प्रलेखन एक उपयोगकर्ता की विचार प्रक्रिया के साथ लिखा जाता है, न कि एक डेवलपर। इस तरह से अपने स्वयं के प्रलेखन का अनुमोदन करने से आपको अपने स्वयं के टुकड़े को व्यवस्थित करने में बेहतर परिप्रेक्ष्य मिलेगा.

2. मानक का पालन करें

कोड के साथ इनलाइन जाता है कि प्रलेखन जोड़ने में, भाषा से अपेक्षित मानक का उपयोग करें. प्रत्येक फ़ंक्शन, चर, साथ ही फ़ंक्शन द्वारा दिए गए मान का वर्णन करना हमेशा एक अच्छा विचार होता है। यहाँ PHP के लिए अच्छा इनलाइन प्रलेखन का एक उदाहरण है.

 / ** * कस्टम क्लासेस को बॉडी क्लासेस के एरे में जोड़ता है। * @ अपरम सरणी $ वर्ग शरीर तत्व के लिए कक्षाएं। * @return array * / function body_classes ($ classes) // 1 से अधिक प्रकाशित लेखक वाले ब्लॉग-समूह की एक क्लास जोड़ता है। if (is_multi_author ()) $ कक्षाएं [] = 'समूह-ब्लॉग';  $ कक्षाएं लौटाएं;  add_filter ('body_class', 'body_classes'); 

निम्नलिखित PHP, जावास्क्रिप्ट और सीएसएस में सर्वोत्तम प्रथाओं के साथ इनलाइन प्रलेखन प्रारूपण के लिए कुछ संदर्भ हैं:

• पीएचपी: वर्डप्रेस के लिए PHP डॉक्यूमेंटेशन स्टैंडर्ड
• जावास्क्रिप्ट: UseJSDoc
• सीएसएस: CSSDoc

यदि आप SublimeText का उपयोग कर रहे हैं, तो मैं DocBlockr को स्थापित करने का सुझाव दूंगा जो कि आपके कोड को इनलाइन प्रलेखन के लिए चतुराई से पूर्व-आबाद करेगा.

3. ग्राफिकल तत्व

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

निम्नलिखित टॉवर ऐप का एक उदाहरण है जहां से आप प्रेरणा ले सकते हैं। वे कुशलतापूर्वक समझाते हैं कि कैसे संस्करण नियंत्रण एक मनभावन तरीके से काम करता है जो इसे सादे पाठ कमांड लाइनों का उपयोग करने की तुलना में अधिक समझ में आता है.

4. सेक्शनिंग

आप बुलेटेड सूचियों और तालिकाओं के भीतर प्रलेखन में कुछ चीजों को लपेटने पर विचार कर सकते हैं क्योंकि इससे उपयोगकर्ताओं के लिए स्कैन और पढ़ने में अधिक समय लगता है.

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

5. संशोधित और अद्यतन

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