ओपन सोर्स प्रलेखन मानक

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

प्रेरणा

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

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

किसी भी मामले में, यह केवल मानक का पहला मसौदा है जिसे मैं प्रस्तावित करता हूं। टिप्पणियों का स्वागत है!

मानक (पहला मसौदा)

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

भागों के क्रम को विनियमित किया जाना चाहिए। मेरे द्वारा दिए गए दो हिस्सों (IV और V) को स्पष्ट आदेश की आवश्यकता नहीं है, लेकिन सामान्य तौर पर शुरुआत के लिए यह स्पष्ट होना चाहिए। किसी को यह समझने में समय बर्बाद नहीं करना चाहिए कि दस्तावेज कैसे पढ़ें।

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

कृपया ध्यान दें कि इस स्तर पर मैं वर्गों के लिए एक औपचारिक शीर्षक का प्रस्ताव नहीं करता हूं, और मुझे यकीन नहीं है कि क्या विशिष्ट नाम वास्तव में मानक का हिस्सा होना चाहिए।

I. यह क्या है और यह आपके लिए कैसे उपयोगी हो सकता है

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

• यह किस कार्य को हल करता है
• इसे कैसे काम करें (पर्यावरण, निर्भरताएं)
• इसके दोष
• इसका विशेष रूप से इरादा नहीं है
• कैसे वे analogues के साथ तुलना करते हैं

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

द्वितीय। इसे कैसे डाउनलोड / खरीदना, स्थापित करना और कॉन्फ़िगर करना

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

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

तृतीय। इसका उपयोग कैसे शुरू करें (ट्यूटोरियल)

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

चतुर्थ। अधिक जटिल चीजें कैसे करें (विषयगत गाइड)

ऊपर के तीन भाग प्रायः रिपॉजिटरी या सोर्स आर्काइव की README फाइल में पाए जाते हैं। यह पहला भाग है, जो कहीं और स्थित होने की संभावना है, क्योंकि यह एक समय में क्रमिक रूप से पढ़ा जा सकता है। ऐसा करने के लिए, इसे अच्छी तरह से अनुक्रमित किया जाना चाहिए (कम से कम सामग्री की एक तालिका होती है) और बढ़ती जटिलता के क्रम में व्यवस्थित अलग मैनुअल होते हैं। अमूर्त दिलचस्प उदाहरणों के साथ आना मुश्किल है, इसलिए यह वर्णन करके शुरू करें कि आप अपने उत्पाद का उपयोग कैसे करते हैं, या आप इसका उपयोग कैसे करना चाहते हैं। यदि आपसे पूछा जाए कि "___ कैसे करें?", तो प्रलेखन के इस भाग में प्रश्न का उत्तर जोड़ें।

वी। एपीआई मदद (स्वतः उत्पन्न)

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

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

संक्षेप में, जब आप कोड नहीं लिख रहे हैं, तो आपने जो पहले ही लिखा है उस पर वापस जाएं और अपने तरीकों पर टिप्पणी में विवरण जोड़ें, ताकि सभी मापदंडों का अर्थ समझ में आए।

प्रश्न, समस्याएं और विचार

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

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

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

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