सॉफ़्टवेयर डॉक्यूमेंटेशन: Difference between revisions

From Vigyanwiki
No edit summary
Line 3: Line 3:
[[सॉफ़्टवेयर|सॉफ़्टवेयर प्रलेखन]] लिखित पाठ या चित्रण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। प्रलेखन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है।
[[सॉफ़्टवेयर|सॉफ़्टवेयर प्रलेखन]] लिखित पाठ या चित्रण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। प्रलेखन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है।


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


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


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


एंटरप्राइज़ सॉफ़्टवेयर विकास में डिज़ाइन दस्तावेज़ का एक बहुत महत्वपूर्ण हिस्सा डेटाबेस डिज़ाइन दस्तावेज़ (डीडीडी) है। इसमें वैचारिक, तार्किक और भौतिक डिज़ाइन तत्व शामिल हैं। DDD में वह औपचारिक जानकारी शामिल होती है जिसकी डेटाबेस के साथ इंटरैक्ट करने वाले लोगों को आवश्यकता होती है। इसे तैयार करने का उद्देश्य दृश्य के भीतर सभी खिलाड़ियों द्वारा उपयोग किए जाने वाला एक सामान्य स्रोत बनाना है। संभावित उपयोगकर्ता हैं:
एंटरप्राइज़ सॉफ़्टवेयर विकास में डिज़ाइन प्रलेखन का बहुत महत्वपूर्ण भाग डेटाबेस डिज़ाइन प्रलेखन (डीडीडी) है। इसमें वैचारिक, तार्किक और भौतिक डिज़ाइन तत्व सम्मिलित हैं। डीडीडी में वह विधिवत जानकारी सम्मिलित होती है जिसकी डेटाबेस के साथ इंटरैक्ट करने वाले लोगों को आवश्यकता होती है। इसे तैयार करने का उद्देश्य दृश्य के भीतर सभी खिलाड़ियों द्वारा उपयोग किए जाने वाला एक सामान्य स्रोत बनाना है। संभावित उपयोगकर्ता हैं:
*डेटाबेस डिज़ाइनर
*डेटाबेस डिज़ाइनर
*डेटाबेस डेवलपर
*डेटाबेस डेवलपर
Line 35: Line 35:
*[[प्रोग्रामर]]
*[[प्रोग्रामर]]


[[ संबंध का डेटाबेस ]] सिस्टम के बारे में बात करते समय, दस्तावेज़ में निम्नलिखित भाग शामिल होने चाहिए:
[[ संबंध का डेटाबेस ]] सिस्टम के बारे में बात करते समय, प्रलेखन में निम्नलिखित भाग सम्मिलित होने चाहिए:
*इकाई-संबंध मॉडल|इकाई - संबंध स्कीमा ([[उन्नत इकाई-संबंध मॉडल]] या नहीं), जिसमें निम्नलिखित जानकारी और उनकी स्पष्ट परिभाषाएँ शामिल हैं:
*इकाई - रेलशनशिप स्कीमा ([[उन्नत इकाई-संबंध मॉडल]] या नहीं), जिसमें निम्नलिखित जानकारी और उनकी स्पष्ट परिभाषाएँ सम्मिलित हैं:
**इकाई सेट और उनकी विशेषताएँ
**इकाई सेट और उनकी विशेषताएँ
**रिश्ते और उनकी विशेषताएँ
**रेलशनशिप और उनकी विशेषताएँ
**प्रत्येक इकाई सेट के लिए उम्मीदवार कुंजी
**प्रत्येक इकाई सेट के लिए कैंडिडेट कुंजी
**विशेषता और टुपल आधारित बाधाएँ
**विशेषता और टुपल आधारित बाधाएँ
*संबंधपरक स्कीमा, जिसमें निम्नलिखित जानकारी शामिल है:
*रिलेशन स्कीमा, जिसमें निम्नलिखित जानकारी सम्मिलित है:
**तालिकाएँ, विशेषताएँ और उनके गुण
**तालिकाएँ, विशेषताएँ और उनके गुण
**दृश्य
**दृश्य
Line 49: Line 49:
**प्राथमिक कुंजी
**प्राथमिक कुंजी


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


== तकनीकी दस्तावेज ==
== तकनीकी दस्तावेज ==


{{Main article|Technical documentation}}
{{Main article|Technical documentation}}
स्रोत कोड (जिसमें [[रीडमी]] फ़ाइलें और [[एपीआई]] दस्तावेज़ शामिल हो सकते हैं) से जुड़े कोड दस्तावेज़ों का संपूर्ण होना ज़रूरी है, लेकिन इतना विस्तृत नहीं कि उन्हें बनाए रखना अत्यधिक समय लेने वाला या मुश्किल हो जाए। [[एपीआई लेखक]]ों द्वारा प्रलेखित किए जा रहे सॉफ़्टवेयर एप्लिकेशन या सॉफ़्टवेयर उत्पाद के लिए विभिन्न कैसे-कैसे और अवलोकन दस्तावेज़ीकरण मार्गदर्शिकाएँ आमतौर पर विशिष्ट पाई जाती हैं। इस दस्तावेज़ का उपयोग डेवलपर्स, परीक्षकों और अंतिम-उपयोगकर्ताओं द्वारा भी किया जा सकता है। आज, बिजली, ऊर्जा, परिवहन, नेटवर्क, एयरोस्पेस, सुरक्षा, सुरक्षा, उद्योग स्वचालन और कई अन्य डोमेन के क्षेत्रों में बहुत सारे उच्च-स्तरीय अनुप्रयोग देखे जाते हैं। ऐसे संगठनों के भीतर तकनीकी दस्तावेज़ीकरण महत्वपूर्ण हो गया है क्योंकि समय के साथ वास्तुकला में बदलाव के साथ जानकारी का बुनियादी और उन्नत स्तर बदल सकता है।
स्रोत कोड (जिसमें [[रीडमी]] फ़ाइलें और [[एपीआई]] दस्तावेज़ शामिल हो सकते हैं) से जुड़े कोड दस्तावेज़ों का संपूर्ण होना ज़रूरी है, लेकिन इतना विस्तृत नहीं कि उन्हें बनाए रखना अत्यधिक समय लेने वाला या मुश्किल हो जाए। [[एपीआई लेखक]]ों द्वारा प्रलेखित किए जा रहे सॉफ़्टवेयर एप्लिकेशन या सॉफ़्टवेयर उत्पाद के लिए विभिन्न कैसे-कैसे और अवलोकन   प्रलेखन मार्गदर्शिकाएँ आमतौर पर विशिष्ट पाई जाती हैं। इस दस्तावेज़ का उपयोग डेवलपर्स, परीक्षकों और अंतिम-उपयोगकर्ताओं द्वारा भी किया जा सकता है। आज, बिजली, ऊर्जा, परिवहन, नेटवर्क, एयरोस्पेस, सुरक्षा, सुरक्षा, उद्योग स्वचालन और कई अन्य डोमेन के क्षेत्रों में बहुत सारे उच्च-स्तरीय अनुप्रयोग देखे जाते हैं। ऐसे संगठनों के भीतर तकनीकी   प्रलेखन महत्वपूर्ण हो गया है क्योंकि समय के साथ वास्तुकला में बदलाव के साथ जानकारी का बुनियादी और उन्नत स्तर बदल सकता है।


कोड दस्तावेज़ों को अक्सर एक संदर्भ गाइड शैली में व्यवस्थित किया जाता है, जिससे प्रोग्रामर को एक मनमाना फ़ंक्शन या क्लास को तुरंत देखने की अनुमति मिलती है।
कोड दस्तावेज़ों को अक्सर एक संदर्भ गाइड शैली में व्यवस्थित किया जाता है, जिससे प्रोग्रामर को एक मनमाना फ़ंक्शन या क्लास को तुरंत देखने की अनुमति मिलती है।
Line 60: Line 60:
=== स्रोत कोड में एम्बेडेड तकनीकी दस्तावेज़ ===
=== स्रोत कोड में एम्बेडेड तकनीकी दस्तावेज़ ===


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


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


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


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


==== व्याख्यात्मक प्रोग्रामिंग ====
==== व्याख्यात्मक प्रोग्रामिंग ====
व्याख्यात्मक प्रोग्रामिंग वास्तविक प्रोग्रामिंग संदर्भों में साक्षर प्रोग्रामिंग के व्यावहारिक अनुप्रयोगों का परिणाम है। व्याख्यात्मक प्रतिमान का प्रस्ताव है कि स्रोत कोड और दस्तावेज़ीकरण को अलग-अलग संग्रहीत किया जाना चाहिए।
व्याख्यात्मक प्रोग्रामिंग वास्तविक प्रोग्रामिंग संदर्भों में साक्षर प्रोग्रामिंग के व्यावहारिक अनुप्रयोगों का परिणाम है। व्याख्यात्मक प्रतिमान का प्रस्ताव है कि स्रोत कोड और   प्रलेखन को अलग-अलग संग्रहीत किया जाना चाहिए।


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


== उपयोगकर्ता दस्तावेज़ ==
== उपयोगकर्ता दस्तावेज़ ==
Line 79: Line 79:
[[लाइब्रेरी (कंप्यूटिंग)]] के मामले में, कोड दस्तावेज़ और उपयोगकर्ता दस्तावेज़ कुछ मामलों में प्रभावी रूप से समकक्ष और जुड़ने लायक हो सकते हैं, लेकिन सामान्य अनुप्रयोग के लिए यह अक्सर सच नहीं होता है।
[[लाइब्रेरी (कंप्यूटिंग)]] के मामले में, कोड दस्तावेज़ और उपयोगकर्ता दस्तावेज़ कुछ मामलों में प्रभावी रूप से समकक्ष और जुड़ने लायक हो सकते हैं, लेकिन सामान्य अनुप्रयोग के लिए यह अक्सर सच नहीं होता है।


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


उपयोगकर्ता दस्तावेज़ीकरण विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।<ref>{{cite web| url = http://dl.acm.org/citation.cfm?id=2775457| title = RH Earle, MA Rosso, KE Alexander (2015) User preferences of software documentation genres. Proceedings of the 33rd Annual International Conference on the Design of Communication (ACM SIGDOC).}}</ref> हालाँकि, तीन व्यापक तरीके हैं जिनसे उपयोगकर्ता दस्तावेज़ीकरण को व्यवस्थित किया जा सकता है।
उपयोगकर्ता   प्रलेखन विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।<ref>{{cite web| url = http://dl.acm.org/citation.cfm?id=2775457| title = RH Earle, MA Rosso, KE Alexander (2015) User preferences of software documentation genres. Proceedings of the 33rd Annual International Conference on the Design of Communication (ACM SIGDOC).}}</ref> हालाँकि, तीन व्यापक तरीके हैं जिनसे उपयोगकर्ता   प्रलेखन को व्यवस्थित किया जा सकता है।
# [[ट्यूटोरियल]]: एक नए उपयोगकर्ता के लिए एक ट्यूटोरियल दृष्टिकोण सबसे उपयोगी माना जाता है, जिसमें उन्हें विशेष कार्यों को पूरा करने के प्रत्येक चरण के माध्यम से निर्देशित किया जाता है।<ref name=kdp>{{cite web
# [[ट्यूटोरियल]]: एक नए उपयोगकर्ता के लिए एक ट्यूटोरियल दृष्टिकोण सबसे उपयोगी माना जाता है, जिसमें उन्हें विशेष कार्यों को पूरा करने के प्रत्येक चरण के माध्यम से निर्देशित किया जाता है।<ref name=kdp>{{cite web
   | last = Woelz  
   | last = Woelz  
Line 97: Line 97:
# सूची या संदर्भ: अंतिम प्रकार का आयोजन सिद्धांत वह है जिसमें आदेशों या कार्यों को केवल वर्णानुक्रम में या तार्किक रूप से समूहीकृत किया जाता है, अक्सर क्रॉस-रेफर्ड इंडेक्स के माध्यम से। यह बाद वाला दृष्टिकोण उन उन्नत उपयोगकर्ताओं के लिए अधिक उपयोगी है जो जानते हैं कि वे किस प्रकार की जानकारी की तलाश कर रहे हैं।
# सूची या संदर्भ: अंतिम प्रकार का आयोजन सिद्धांत वह है जिसमें आदेशों या कार्यों को केवल वर्णानुक्रम में या तार्किक रूप से समूहीकृत किया जाता है, अक्सर क्रॉस-रेफर्ड इंडेक्स के माध्यम से। यह बाद वाला दृष्टिकोण उन उन्नत उपयोगकर्ताओं के लिए अधिक उपयोगी है जो जानते हैं कि वे किस प्रकार की जानकारी की तलाश कर रहे हैं।


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


=== उपयोगकर्ता दस्तावेज़ तैयार करना ===
=== उपयोगकर्ता दस्तावेज़ तैयार करना ===
तकनीकी दस्तावेज़ीकरण के अन्य रूपों की तरह, अच्छे उपयोगकर्ता दस्तावेज़ीकरण को विकास की एक संगठित प्रक्रिया से लाभ मिलता है। उपयोगकर्ता दस्तावेज़ीकरण के मामले में, उद्योग में आमतौर पर होने वाली प्रक्रिया में पाँच चरण होते हैं:<ref>Thomas T. Barker, [http://www.writingsoftwaredocumentation.com/index.htm Writing Software Documentation], Preface, xxiv. Part of the [[Allyn & Bacon]] Series in Technical Communication, 2nd ed. [[Upper Saddle River, New Jersey|Upper Saddle River]]: [[Pearson Education]], 2003. {{ISBN|0321103289}} {{webarchive |url=https://web.archive.org/web/20130513033153/http://www.writingsoftwaredocumentation.com/index.htm |date=May 13, 2013 }}</ref>
तकनीकी   प्रलेखन के अन्य रूपों की तरह, अच्छे उपयोगकर्ता   प्रलेखन को विकास की एक संगठित प्रक्रिया से लाभ मिलता है। उपयोगकर्ता   प्रलेखन के मामले में, उद्योग में आमतौर पर होने वाली प्रक्रिया में पाँच चरण होते हैं:<ref>Thomas T. Barker, [http://www.writingsoftwaredocumentation.com/index.htm Writing Software Documentation], Preface, xxiv. Part of the [[Allyn & Bacon]] Series in Technical Communication, 2nd ed. [[Upper Saddle River, New Jersey|Upper Saddle River]]: [[Pearson Education]], 2003. {{ISBN|0321103289}} {{webarchive |url=https://web.archive.org/web/20130513033153/http://www.writingsoftwaredocumentation.com/index.htm |date=May 13, 2013 }}</ref>
# [[उपयोगकर्ता विश्लेषण]], प्रक्रिया का मूल अनुसंधान चरण।<ref>Barker, pg. 118.</ref>
# [[उपयोगकर्ता विश्लेषण]], प्रक्रिया का मूल अनुसंधान चरण।<ref>Barker, pg. 118.</ref>
# योजना, या वास्तविक दस्तावेज़ीकरण चरण।<ref>Barker, pg. 173.</ref>
# योजना, या वास्तविक   प्रलेखन चरण।<ref>Barker, pg. 173.</ref>
# ड्राफ्ट समीक्षा, एक आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।<ref>Barker, pg. 217.</ref>
# ड्राफ्ट समीक्षा, एक आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।<ref>Barker, pg. 217.</ref>
# प्रयोज्यता परीक्षण, जिसके द्वारा दस्तावेज़ की प्रयोज्यता का अनुभवजन्य परीक्षण किया जाता है।<ref>Barker, pg. 240.</ref>
# प्रयोज्यता परीक्षण, जिसके द्वारा दस्तावेज़ की प्रयोज्यता का अनुभवजन्य परीक्षण किया जाता है।<ref>Barker, pg. 240.</ref>
# [[संपादन]], अंतिम चरण जिसमें चरण तीन और चार में एकत्र की गई जानकारी का उपयोग अंतिम मसौदा तैयार करने के लिए किया जाता है।
# [[संपादन]], अंतिम चरण जिसमें चरण तीन और चार में एकत्र की गई जानकारी का उपयोग अंतिम मसौदा तैयार करने के लिए किया जाता है।


== दस्तावेज़ीकरण और त्वरित विकास विवाद ==
== प्रलेखन और त्वरित विकास विवाद ==
  डेवलपर्स के बीच दस्तावेज़ीकरण का विरोध सर्वविदित है और इस पर जोर देने की आवश्यकता नहीं है।<ref>Herbsleb, James D. and Moitra, Dependra. In: ''IEEE Software'', vol. 18, no. 2, pp.  16-20, Mar/Apr 2001</ref> यह स्थिति विशेष रूप से फुर्तीली सॉफ्टवेयर विकास में प्रचलित है क्योंकि ये पद्धतियाँ किसी भी अनावश्यक गतिविधियों से बचने की कोशिश करती हैं जो सीधे तौर पर मूल्य नहीं लाती हैं।
  डेवलपर्स के बीच   प्रलेखन का विरोध सर्वविदित है और इस पर जोर देने की आवश्यकता नहीं है।<ref>Herbsleb, James D. and Moitra, Dependra. In: ''IEEE Software'', vol. 18, no. 2, pp.  16-20, Mar/Apr 2001</ref> यह स्थिति विशेष रूप से फुर्तीली सॉफ्टवेयर विकास में प्रचलित है क्योंकि ये पद्धतियाँ किसी भी अनावश्यक गतिविधियों से बचने की कोशिश करती हैं जो सीधे तौर पर मूल्य नहीं लाती हैं।
विशेष रूप से, [[द एजाइल मेनिफेस्टो]] व्यापक दस्तावेज़ीकरण की तुलना में कामकाजी सॉफ़्टवेयर को महत्व देने की वकालत करता है, जिसकी व्याख्या निंदनीय रूप से की जा सकती है क्योंकि हम अपना सारा समय कोडिंग में बिताना चाहते हैं। याद रखें, वास्तविक प्रोग्रामर दस्तावेज़ीकरण नहीं लिखते हैं।<ref>Rakitin, Steven. , [http://csse.usc.edu/events/2002/arr/letters.pdf "Manifesto elicits cynicism."] IEEE Computer, vol. 34, no. 12, p. 4, 2001</ref>
विशेष रूप से, [[द एजाइल मेनिफेस्टो]] व्यापक   प्रलेखन की तुलना में कामकाजी सॉफ़्टवेयर को महत्व देने की वकालत करता है, जिसकी व्याख्या निंदनीय रूप से की जा सकती है क्योंकि हम अपना सारा समय कोडिंग में बिताना चाहते हैं। याद रखें, वास्तविक प्रोग्रामर   प्रलेखन नहीं लिखते हैं।<ref>Rakitin, Steven. , [http://csse.usc.edu/events/2002/arr/letters.pdf "Manifesto elicits cynicism."] IEEE Computer, vol. 34, no. 12, p. 4, 2001</ref>
हालाँकि, सॉफ्टवेयर इंजीनियरिंग विशेषज्ञों के बीच एक सर्वेक्षण से पता चला है कि त्वरित विकास में दस्तावेज़ीकरण को किसी भी तरह से अनावश्यक नहीं माना जाता है।
हालाँकि, सॉफ्टवेयर इंजीनियरिंग विशेषज्ञों के बीच एक सर्वेक्षण से पता चला है कि त्वरित विकास में   प्रलेखन को किसी भी तरह से अनावश्यक नहीं माना जाता है।
फिर भी यह स्वीकार किया जाता है कि विकास में प्रेरक समस्याएं हैं, और त्वरित विकास के अनुरूप दस्तावेज़ीकरण विधियों (उदाहरण के लिए [[प्रतिष्ठा प्रणाली]] और [[ gamification ]] के माध्यम से) की आवश्यकता हो सकती है।<ref>Prause, Christian R., and Zoya Durdik. "Architectural design and documentation: Waste in agile development?" In: ''International Conference on Software and System Process'' (ICSSP), IEEE, 2012.</ref><ref>Selic, Bran. "Agile documentation, anyone?" In: ''IEEE Software'', vol. 26, no. 6, pp. 11-12, 2009</ref>
फिर भी यह स्वीकार किया जाता है कि विकास में प्रेरक समस्याएं हैं, और त्वरित विकास के अनुरूप   प्रलेखन विधियों (उदाहरण के लिए [[प्रतिष्ठा प्रणाली]] और [[ gamification ]] के माध्यम से) की आवश्यकता हो सकती है।<ref>Prause, Christian R., and Zoya Durdik. "Architectural design and documentation: Waste in agile development?" In: ''International Conference on Software and System Process'' (ICSSP), IEEE, 2012.</ref><ref>Selic, Bran. "Agile documentation, anyone?" In: ''IEEE Software'', vol. 26, no. 6, pp. 11-12, 2009</ref>




==विपणन दस्तावेज़ ==
==विपणन दस्तावेज़ ==
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को उत्पाद के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। दस्तावेज़ीकरण के इस रूप के तीन उद्देश्य हैं:
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को उत्पाद के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है।   प्रलेखन के इस रूप के तीन उद्देश्य हैं:


# संभावित उपयोगकर्ता को उत्पाद के बारे में उत्साहित करना और उनमें इसके साथ और अधिक जुड़ने की इच्छा पैदा करना।
# संभावित उपयोगकर्ता को उत्पाद के बारे में उत्साहित करना और उनमें इसके साथ और अधिक जुड़ने की इच्छा पैदा करना।
Line 123: Line 123:
== यह भी देखें ==
== यह भी देखें ==
* एपीआई लेखक
* एपीआई लेखक
* [[दस्तावेज़ीकरण जनरेटर की तुलना]]
*   [[दस्तावेज़ीकरण जनरेटर की तुलना|प्रलेखन जनरेटर की तुलना]]
* अनुबंध द्वारा डिज़ाइन
* अनुबंध द्वारा डिज़ाइन
* डिज़ाइन दस्तावेज़
* डिज़ाइन दस्तावेज़

Revision as of 13:11, 18 July 2023

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

प्रलेखन सॉफ़्टवेयर इंजीनियरिंग का एक महत्वपूर्ण हिस्सा है। प्रलेखन के प्रकारों में शामिल हैं:

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

आवश्यकताएँ दस्तावेज़

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

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

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

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

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

एजाइल सॉफ्टवेयर विकास में, आवश्यकताओं को अधिकांशतः स्वीकृति मानदंडों के साथ उपयोगकर्ता कहानियों के रूप में व्यक्त किया जाता है।

आर्किटेक्चर डिज़ाइन दस्तावेज़

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

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

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

संबंध का डेटाबेस सिस्टम के बारे में बात करते समय, प्रलेखन में निम्नलिखित भाग सम्मिलित होने चाहिए:

  • इकाई - रेलशनशिप स्कीमा (उन्नत इकाई-संबंध मॉडल या नहीं), जिसमें निम्नलिखित जानकारी और उनकी स्पष्ट परिभाषाएँ सम्मिलित हैं:
    • इकाई सेट और उनकी विशेषताएँ
    • रेलशनशिप और उनकी विशेषताएँ
    • प्रत्येक इकाई सेट के लिए कैंडिडेट कुंजी
    • विशेषता और टुपल आधारित बाधाएँ
  • रिलेशन स्कीमा, जिसमें निम्नलिखित जानकारी सम्मिलित है:
    • तालिकाएँ, विशेषताएँ और उनके गुण
    • दृश्य
    • प्राथमिक कुंजी, विदेशी कुंजी जैसी बाधाएं,
    • संदर्भात्मक बाधाओं की प्रमुखता
    • संदर्भात्मक बाधाओं के लिए कैस्केडिंग नीति
    • प्राथमिक कुंजी

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

तकनीकी दस्तावेज

Main article: Technical documentation

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

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

स्रोत कोड में एम्बेडेड तकनीकी दस्तावेज़

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

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

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

साक्षर प्रोग्रामिंग

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

व्याख्यात्मक प्रोग्रामिंग

व्याख्यात्मक प्रोग्रामिंग वास्तविक प्रोग्रामिंग संदर्भों में साक्षर प्रोग्रामिंग के व्यावहारिक अनुप्रयोगों का परिणाम है। व्याख्यात्मक प्रतिमान का प्रस्ताव है कि स्रोत कोड और प्रलेखन को अलग-अलग संग्रहीत किया जाना चाहिए।

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

उपयोगकर्ता दस्तावेज़

कोड दस्तावेज़ों के विपरीत, उपयोगकर्ता दस्तावेज़ केवल यह वर्णन करते हैं कि किसी प्रोग्राम का उपयोग कैसे किया जाता है।

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

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

उपयोगकर्ता प्रलेखन विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।[1] हालाँकि, तीन व्यापक तरीके हैं जिनसे उपयोगकर्ता प्रलेखन को व्यवस्थित किया जा सकता है।

  1. ट्यूटोरियल: एक नए उपयोगकर्ता के लिए एक ट्यूटोरियल दृष्टिकोण सबसे उपयोगी माना जाता है, जिसमें उन्हें विशेष कार्यों को पूरा करने के प्रत्येक चरण के माध्यम से निर्देशित किया जाता है।[2] # विषयगत: एक थीम (साहित्य) दृष्टिकोण, जहां अध्याय या अनुभाग रुचि के एक विशेष क्षेत्र पर ध्यान केंद्रित करते हैं, एक मध्यवर्ती उपयोगकर्ता के लिए अधिक सामान्य उपयोग का होता है। कुछ लेखक उपयोगकर्ता की ज़रूरतों को पूरा करने के लिए ज्ञान आधारित लेख के माध्यम से अपने विचार व्यक्त करना पसंद करते हैं। यह दृष्टिकोण आमतौर पर सूचना प्रौद्योगिकी जैसे गतिशील उद्योग द्वारा अपनाया जाता है।[3]
  2. सूची या संदर्भ: अंतिम प्रकार का आयोजन सिद्धांत वह है जिसमें आदेशों या कार्यों को केवल वर्णानुक्रम में या तार्किक रूप से समूहीकृत किया जाता है, अक्सर क्रॉस-रेफर्ड इंडेक्स के माध्यम से। यह बाद वाला दृष्टिकोण उन उन्नत उपयोगकर्ताओं के लिए अधिक उपयोगी है जो जानते हैं कि वे किस प्रकार की जानकारी की तलाश कर रहे हैं।

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

उपयोगकर्ता दस्तावेज़ तैयार करना

तकनीकी प्रलेखन के अन्य रूपों की तरह, अच्छे उपयोगकर्ता प्रलेखन को विकास की एक संगठित प्रक्रिया से लाभ मिलता है। उपयोगकर्ता प्रलेखन के मामले में, उद्योग में आमतौर पर होने वाली प्रक्रिया में पाँच चरण होते हैं:[4]

  1. उपयोगकर्ता विश्लेषण, प्रक्रिया का मूल अनुसंधान चरण।[5]
  2. योजना, या वास्तविक प्रलेखन चरण।[6]
  3. ड्राफ्ट समीक्षा, एक आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।[7]
  4. प्रयोज्यता परीक्षण, जिसके द्वारा दस्तावेज़ की प्रयोज्यता का अनुभवजन्य परीक्षण किया जाता है।[8]
  5. संपादन, अंतिम चरण जिसमें चरण तीन और चार में एकत्र की गई जानकारी का उपयोग अंतिम मसौदा तैयार करने के लिए किया जाता है।

प्रलेखन और त्वरित विकास विवाद

डेवलपर्स के बीच    प्रलेखन का विरोध सर्वविदित है और इस पर जोर देने की आवश्यकता नहीं है।[9] यह स्थिति विशेष रूप से फुर्तीली सॉफ्टवेयर विकास में प्रचलित है क्योंकि ये पद्धतियाँ किसी भी अनावश्यक गतिविधियों से बचने की कोशिश करती हैं जो सीधे तौर पर मूल्य नहीं लाती हैं।

विशेष रूप से, द एजाइल मेनिफेस्टो व्यापक प्रलेखन की तुलना में कामकाजी सॉफ़्टवेयर को महत्व देने की वकालत करता है, जिसकी व्याख्या निंदनीय रूप से की जा सकती है क्योंकि हम अपना सारा समय कोडिंग में बिताना चाहते हैं। याद रखें, वास्तविक प्रोग्रामर प्रलेखन नहीं लिखते हैं।[10] हालाँकि, सॉफ्टवेयर इंजीनियरिंग विशेषज्ञों के बीच एक सर्वेक्षण से पता चला है कि त्वरित विकास में प्रलेखन को किसी भी तरह से अनावश्यक नहीं माना जाता है। फिर भी यह स्वीकार किया जाता है कि विकास में प्रेरक समस्याएं हैं, और त्वरित विकास के अनुरूप प्रलेखन विधियों (उदाहरण के लिए प्रतिष्ठा प्रणाली और gamification के माध्यम से) की आवश्यकता हो सकती है।[11][12]


विपणन दस्तावेज़

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

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

यह भी देखें

टिप्पणियाँ

  1. ↑ "RH Earle, MA Rosso, KE Alexander (2015) User preferences of software documentation genres. Proceedings of the 33rd Annual International Conference on the Design of Communication (ACM SIGDOC)".
  2. ↑ Woelz, Carlos. "The KDE Documentation Primer". Retrieved 15 June 2009.
  3. ↑ Microsoft. "Knowledge Base Articles for Driver Development". Microsoft. Retrieved 15 June 2009.
  4. ↑ Thomas T. Barker, Writing Software Documentation, Preface, xxiv. Part of the Allyn & Bacon Series in Technical Communication, 2nd ed. Upper Saddle River: Pearson Education, 2003. ISBN 0321103289 Archived May 13, 2013, at the Wayback Machine
  5. ↑ Barker, pg. 118.
  6. ↑ Barker, pg. 173.
  7. ↑ Barker, pg. 217.
  8. ↑ Barker, pg. 240.
  9. ↑ Herbsleb, James D. and Moitra, Dependra. In: IEEE Software, vol. 18, no. 2, pp. 16-20, Mar/Apr 2001
  10. ↑ Rakitin, Steven. , "Manifesto elicits cynicism." IEEE Computer, vol. 34, no. 12, p. 4, 2001
  11. ↑ Prause, Christian R., and Zoya Durdik. "Architectural design and documentation: Waste in agile development?" In: International Conference on Software and System Process (ICSSP), IEEE, 2012.
  12. ↑ Selic, Bran. "Agile documentation, anyone?" In: IEEE Software, vol. 26, no. 6, pp. 11-12, 2009

[Category:Technical communicati

Retrieved from ‘https://www.vigyanwiki.in/index.php?title=सॉफ़्टवेयर_डॉक्यूमेंटेशन&oldid=228751’