मुफ्त और खुले सॉफ्टवेयर विकसित करने के लिए अच्छी प्रथाएँ: प्रलेखन

La प्रलेखन है और एक मौलिक हिस्सा होना चाहिए रचनात्मक प्रक्रिया और योजना सभी मानव गतिविधि में, और तकनीकी क्षेत्र में और अधिक, विशेष रूप से के क्षेत्र में सॉफ्टवेयर विकास.

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

इसके अलावा, के विशिष्ट मामले में मुफ्त सॉफ्टवेयर प्रलेखन महत्वपूर्ण है, क्योंकि यह पूरी तरह से गारंटी देने की अनुमति देता है ज्ञान हस्तांतरण और सशक्तिकरण की संतोषजनक पूर्ति के लिए आवश्यक है 4 स्वतंत्रता इसके द्वारा प्रचारित, जो हैं:

• 0: कार्यक्रम को चलाने की आजादी हालांकि आप चाहते हैं, किसी भी उद्देश्य के लिए।
• 1: किसी प्रोग्राम को एक्सेस करने और उसका अध्ययन करने और इसे बदलने और इसे अपने लाभ के लिए अनुकूलित करने की स्वतंत्रता।
• 2: समान और / या दूसरों को फैलाने के लिए प्रतियां साझा करने या पुनर्वितरित करने की स्वतंत्रता।
• 3: तृतीय पक्षों को अपने संशोधित संस्करणों की प्रतियां वितरित करने की स्वतंत्रता।

एक अच्छा प्रलेखन यह संभव बनाता है, इसलिए, कि निर्मित उत्पाद:

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

अच्छी प्रथाओं: प्रलेखन

Fundamentos

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

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

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

README पाठ फ़ाइलों में प्रलेखन पर अच्छी प्रथाओं

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

हमारे लेख के लिए, हमने लिया है उत्तम आचरण द्वारा परिकल्पित और प्रकट किया गया "विकास पहल के लिए कोड" डेल अंतर अमेरिकी विकास बैंक, जो संक्षेप में हमें बताता है कि एक के आधार पर अच्छा प्रलेखन पाठ फ़ाइल README.md (या .txt) इसे इस प्रकार संरचित किया जाना चाहिए:

अनुशंसित README फ़ाइल संरचना

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

इन में अच्छा अभ्यास, वे भी करने के लिए जोड़ने की सलाह देते हैं README फ़ाइल प्रलेखन इसे और अधिक पूर्ण बनाने के लिए, निम्नलिखित खंड:

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

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

निष्कर्ष

हम आशा करते हैं कि यह "उपयोगी छोटी पोस्ट" के बारे में «Buenas prácticas» के क्षेत्र में «documentación» विकसित करने के लिए बनाने के लिए «Software libre y abierto», पूरे के लिए बहुत रुचि और उपयोगिता है «Comunidad de Software Libre y Código Abierto» और के लिए और के अनुप्रयोगों के अद्भुत, विशाल और बढ़ती पारिस्थितिकी तंत्र के प्रसार में महान योगदान «GNU/Linux».

और अधिक जानकारी के लिए, किसी भी यात्रा करने में हमेशा संकोच न करें ऑनलाइन लाइब्रेरी जैसा OpenLibra y जेडीआईटी पढ़ने के लिए पुस्तकें (PDF) इस विषय पर या अन्य ज्ञान क्षेत्र। अभी के लिए, अगर आपको यह पसंद आया «publicación», इसे साझा करना बंद न करें दूसरों के साथ, अपने में पसंदीदा वेबसाइट, चैनल, समूह या समुदाय सामाजिक नेटवर्क, अधिमानतः मुक्त और के रूप में खुला मेस्टोडोन, या सुरक्षित और निजी की तरह Telegram.

या बस हमारे होम पेज पर जाएँ DesdeLinux या आधिकारिक चैनल से जुड़ें का टेलीग्राम DesdeLinux इस पर या अन्य दिलचस्प प्रकाशनों को पढ़ने और वोट करने के लिए «Software Libre», «Código Abierto», «GNU/Linux» और इससे संबंधित अन्य विषय «Informática y la Computación», और «Actualidad tecnológica».