सॉफ़्टवेयर डॉक्यूमेंटेशन: Difference between revisions
No edit summary |
|||
| (4 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Short description|Explains the functionality of software}} | {{Short description|Explains the functionality of software}} | ||
'''[[सॉफ़्टवेयर|सॉफ़्टवेयर डाक्यूमेंटेशन]]''' लिखित टेक्स्ट या स्पष्टीकरण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। डाक्यूमेंटेशन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है। | |||
[[सॉफ़्टवेयर|सॉफ़्टवेयर डाक्यूमेंटेशन]] लिखित टेक्स्ट या स्पष्टीकरण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। डाक्यूमेंटेशन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है। | |||
डाक्यूमेंटेशन सॉफ़्टवेयर इंजीनियरिंग का एक महत्वपूर्ण भाग है। डाक्यूमेंटेशन के प्रकारों में सम्मिलित हैं: | डाक्यूमेंटेशन सॉफ़्टवेयर इंजीनियरिंग का एक महत्वपूर्ण भाग है। डाक्यूमेंटेशन के प्रकारों में सम्मिलित हैं: | ||
| Line 83: | Line 82: | ||
उपयोगकर्ता डाक्यूमेंटेशन विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।<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 | ||
| first = Carlos | | first = Carlos | ||
| Line 112: | Line 111: | ||
डेवलपर्स के बीच डाक्यूमेंटेशन का विरोध सर्वविदित है और इस पर जोर देने की आवश्यकता नहीं है।<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> चूँकि, सॉफ्टवेयर इंजीनियरिंग विशेषज्ञों के बीच सर्वेक्षण से पता चला है कि त्वरित विकास में डाक्यूमेंटेशन को किसी भी तरह से अनावश्यक नहीं माना जाता है। फिर भी यह स्वीकार किया जाता है कि विकास में प्रेरक समस्याएं हैं, और त्वरित विकास के अनुरूप डाक्यूमेंटेशन विधियों (उदाहरण के लिए [[प्रतिष्ठा प्रणाली|रेपिटूशन सिस्टम]] और [[ 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> | विशेष रूप से, [[द एजाइल मेनिफेस्टो]] व्यापक डाक्यूमेंटेशन की तुलना में सॉफ़्टवेयर डेवलपमेंट को महत्व देने के बारे में बताता है, जिसकी व्याख्या निंदनीय रूप से की जा सकती है क्योंकि हम अपना सारा समय कोडिंग में बिताना चाहते हैं। याद रखें, वास्तविक प्रोग्रामर डाक्यूमेंटेशन नहीं लिखते हैं।<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> | ||
==विपणन दस्तावेज़ == | ==विपणन दस्तावेज़ == | ||
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को प्रोडक्ट के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। डाक्यूमेंटेशन के इस रूप के तीन उद्देश्य हैं: | कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को प्रोडक्ट के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। डाक्यूमेंटेशन के इस रूप के तीन उद्देश्य हैं: | ||
| Line 131: | Line 128: | ||
* रेडमी फाइल | * रेडमी फाइल | ||
* [[उपयोगकर्ता सहायता]] | * [[उपयोगकर्ता सहायता]] | ||
* [[एकीकृत मॉडलिंग भाषा]] यूएमएल | * [[एकीकृत मॉडलिंग भाषा|एकीकृत मॉडलिंग लैंग्वेज]] यूएमएल | ||
== टिप्पणियाँ == | == टिप्पणियाँ == | ||
{{Reflist}} | {{Reflist}} | ||
{{DEFAULTSORT:Software Documentation}} | |||
{{DEFAULTSORT:Software Documentation}} | |||
[[Category: | [[Category:Articles with hatnote templates targeting a nonexistent page|Software Documentation]] | ||
[[Category:Created On 08/07/2023]] | [[Category:Created On 08/07/2023|Software Documentation]] | ||
[[Category:Lua-based templates|Software Documentation]] | |||
[[Category:Machine Translated Page|Software Documentation]] | |||
[[Category:Pages with script errors|Software Documentation]] | |||
[[Category:Templates Vigyan Ready|Software Documentation]] | |||
[[Category:Templates that add a tracking category|Software Documentation]] | |||
[[Category:Templates that generate short descriptions|Software Documentation]] | |||
[[Category:Templates using TemplateData|Software Documentation]] | |||
[[Category:Webarchive template wayback links|Software Documentation]] | |||
[[Category:तकनीकी संचार|Software Documentation]] | |||
[[Category:सॉफ़्टवेयर दस्तावेज़ीकरण| सॉफ़्टवेयर दस्तावेज़ीकरण]] | |||
Latest revision as of 17:57, 29 August 2023
सॉफ़्टवेयर डाक्यूमेंटेशन लिखित टेक्स्ट या स्पष्टीकरण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। डाक्यूमेंटेशन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है।
डाक्यूमेंटेशन सॉफ़्टवेयर इंजीनियरिंग का एक महत्वपूर्ण भाग है। डाक्यूमेंटेशन के प्रकारों में सम्मिलित हैं:
- आवश्यकताएँ - ऐसे कथन जो किसी सिस्टम की विशेषताओं, क्षमताओं, विशेषताओं या गुणों की पहचान करते हैं। जो कार्यान्वित किया जाएगा या किया जा चुका है उसकी आधार यही है।
- आर्टिटेक्चर/डिज़ाइन - सॉफ़्टवेयर का अवलोकन है। इसमें सॉफ़्टवेयर घटकों के डिज़ाइन में उपयोग किए जाने वाले पर्यावरण और निर्माण सिद्धांतों से संबंध सम्मिलित हैं।
- तकनीकी - कोड, एल्गोरिदम, इंटरफेस और एपीआई डाक्यूमेंटेशन का प्रलेखीकरण होता है।
- एन्ड यूजर - अंतिम उपयोगकर्ता, सिस्टम प्रशासक और सहायक कर्मचारियों के लिए नियम होता है।
- मार्केटिंग - प्रोडक्ट का मार्केटिंग कैसे करें और मार्केट की मांग का विश्लेषण कैसे कर सकते हैं।
आवश्यकताएँ दस्तावेज़
डाक्यूमेंटेशन इस बात का विवरण करता करता है कि कोई विशेष सॉफ्टवेयर गुणवत्ता करता है या क्या करेगा। इसका उपयोग सॉफ्टवेयर डेवेलपमेंट के समय यह बताने के लिए किया जाता है कि सॉफ्टवेयर कैसे काम करता है या इसे कैसे संचालित करने का आशय है। इसका उपयोग साझेदारी के रूप में या सॉफ़्टवेयर क्या करेगा, इस पर साझेदारी की नींव के रूप में भी किया जाता है। उत्पाद और उपभोग सॉफ्टवेयर के उत्पादन में सम्मिलित सभी लोगों द्वारा किया जाता है, जिनमें सम्मिलित हैं: एन्ड यूजर, कस्टमर,प्रोजेक्ट मैनेजर, सेल्स, मार्केटिंग, सॉफ़्टवेयर आर्टिटेक, यूजेबिलिटी इंजीनियरिंग, पारस्परिक प्रभाव वाली डिज़ाइन, सॉफ्टवेयर डेवलपमेंट और सॉफ्टवेयर परीक्षण होता है।
आवश्यकताएँ विभिन्न विधियों, अंकन और नियम के पालन में आता है। आवश्यकताएँ लक्ष्य-जैसी हो सकती हैं (उदाहरण के लिए, वितरित कार्य वातावरण), डिज़ाइन के निकट (उदाहरण के लिए, कॉन्फ़िगरेशन फ़ाइल पर राइट-क्लिक करके और 'बिल्ड' फ़ंक्शन का चयन करके निर्माण प्रारम्भ किया जा सकता है), और बीच में कुछ भी हो सकता है। उन्हें नेचुरल भाषा में कथनों के रूप में, खींचे गए आंकड़ों के रूप में, विस्तृत गणितीय सूत्र के रूप में, या उन सभी के संयोजन के रूप में निर्दिष्ट किया जा सकता है।
आवश्यकता डाक्यूमेंटेशन की विविधता और जटिलता इसे सिद्ध बढ़ावा करती है। आवश्यकताएँ अंतर्निहित हो सकती हैं और उन्हें बताना करना कठिन हो सकता है। यह जानना कठिन है कि वास्तव में कितने और किस प्रकार के डाक्यूमेंटेशन की आवश्यकता है और आर्किटेक्चर और डिज़ाइन डाक्यूमेंटेशन के लिए कितना छोड़ा जा सकता है, यह जानना कठिन है कि डाक्यूमेंटेशन को पढ़ने और उपयोग करने वाले लोगों की विविधता को देखते हुए आवश्यकताओं को कैसे डाक्यूमेंटेशन किया जाए। इस प्रकार, डाक्यूमेंटेशन अधिकांशतः अधूरा (या अस्तित्वहीन) होता है। उचित आवश्यकताओं के डाक्यूमेंटेशन के बिना, सॉफ़्टवेयर परिवर्तन अधिक कठिन हो जाते हैं - और इसलिए अधिक त्रुटि संभावी (सॉफ़्टवेयर गुणवत्ता में कमी) और समय लेने वाली (महंगी) होती है।
डाक्यूमेंटेशन की आवश्यकता सामान्यतौर पर उत्पाद की जटिलता, उत्पाद के प्रभाव और सॉफ़्टवेयर के लाइफ एक्सपेंसिव से संबंधित होती है। यदि सॉफ़्टवेयर बहुत जटिल है या कई लोगों द्वारा विकसित किया गया है (उदाहरण के लिए, मोबाइल फ़ोन सॉफ़्टवेयर), तो आवश्यकताएँ बहुत अच्छा संचार में मदद कर सकती हैं कि क्या सिद्ध करना है। यदि सॉफ़्टवेयर सुरक्षा-महत्वपूर्ण है और मानव जीवन पर नकारात्मक प्रभाव डाल सकता है (उदाहरण के लिए, परमाणु ऊर्जा प्रणाली, चिकित्सा उपकरण, यांत्रिक उपकरण), तो अधिक विधिवत आवश्यकताओं के डाक्यूमेंटेशन की अधिकांशतः आवश्यकता होती है। यदि सॉफ़्टवेयर के केवल एक या दो महीने तक चलने की आशा है (उदाहरण के लिए, किसी निश्चित अभियान के लिए विशेष रूप से विकसित किए गए बहुत छोटे मोबाइल फ़ोन एप्लिकेशन) तो बहुत कम आवश्यकताओं वाले डाक्यूमेंटेशन की आवश्यकता हो सकती है। यदि सॉफ़्टवेयर पहली रिलीज़ है जिसे बाद में बनाया गया है, तो सॉफ़्टवेयर के परिवर्तन को प्रबंधित करने और यह सत्यापित करने के लिए आवश्यकताओं का डाक्यूमेंटेशन बहुत सहायक होता है कि संशोधित होने पर सॉफ़्टवेयर परीक्षण कुछ भी टूटा नहीं है।
परंपरागत रूप से, डाक्यूमेंटेशन में निर्दिष्ट किया जाता है (उदाहरण के लिए वर्ड प्रोसेसिंग अनुप्रयोगों और स्प्रेडशीट अनुप्रयोगों का उपयोग करना)। डाक्यूमेंटेशन (और सामान्य रूप से सॉफ़्टवेयर डाक्यूमेंटेशन) की बढ़ती जटिलता और बदलती प्रकृति को प्रबंधित करने के लिए, डेटाबेस-सेंट्रिक सिस्टम और विशेष-उद्देश्यीय आवश्यकताओं के प्रबंधन उपकरणों के बारे में बताई जाती है।
एजाइल सॉफ्टवेयर डेवेलपमेंट में, आवश्यकताओं को अधिकांशतः स्वीकृति मानदंडों के साथ यूजर स्टोरीज के रूप में व्यक्त किया जाता है।
आर्किटेक्चर डिज़ाइन डाक्यूमेंटेशन
आर्किटेक्चर डाक्यूमेंटेशन (सॉफ्टवेयर आर्टिटेक्चर विवरण के रूप में भी जाना जाता है) एक विशेष प्रकार का डिज़ाइन डाक्यूमेंटेशन है। एक तरह से, आर्किटेक्चर डाक्यूमेंटेशन कोड से तीसरा व्युत्पन्न हैं (डिज़ाइन डाक्यूमेंटेशन दूसरा व्युत्पन्न है, और कोड डाक्यूमेंटेशन पहले हैं)। आर्किटेक्चर डाक्यूमेंटेशन में बहुत कम कोड के लिए विशिष्ट है। ये डाक्यूमेंटेशन यह वर्णन नहीं करते हैं कि किसी विशेष दिनचर्या को कैसे प्रोग्राम किया जाए, या यहां तक कि वह विशेष दिनचर्या उस रूप में क्यों उपस्थित है जैसा वह उपस्थित है, अपितु इसके बदले वे केवल सामान्य आवश्यकताओं को बताते हैं जो ऐसी दिनचर्या के अस्तित्व को प्रेरित करेंगे। अच्छा आर्किटेक्चर डाक्यूमेंटेशन विवरण में छोटा परन्तु स्पष्टीकरण में मोटा होता है। यह निचले स्तर के डिज़ाइन के लिए दृष्टिकोण सुझा सकता है, परन्तु वास्तविक अन्वेषण अध्ययन को अन्य डाक्यूमेंटेशन पर छोड़ सकता है।
अन्य प्रकार का डिज़ाइन डाक्यूमेंटेशन तुलना डाक्यूमेंटेशन या ट्रेड का स्टडी है। यह प्रायः वाइट पेपर का रूप ले लेता है। यह प्रणाली के विशिष्ट कथन पर ध्यान केंद्रित करता है और वैकल्पिक दृष्टिकोण सुझाता है। यह उपयोगकर्ता इंटरफ़ेस, कोड, डिज़ाइन या यहां तक कि आर्टिटेक्चरल स्तर पर भी हो सकता है। यह रेखांकित करेगा कि स्थिति क्या है, एक या अधिक विकल्पों का वर्णन करेगा, और प्रत्येक के लाभ और क्षति गिनाएगा। अच्छा ट्रेड स्टडी डाक्यूमेंटेशन शोध पर भारी होता है, अपने विचार को स्पष्ट रूप से व्यक्त करता है (पाठक को चकित करने के लिए अस्पष्ट जारगन पर बहुत अधिक विश्वास किए बिना), और सबसे महत्वपूर्ण बात यह है कि यह निष्पक्ष है। इसे जो भी सर्वोत्तम समाधान प्रस्तुत किया जाए उसकी लागत को ईमानदारी से और स्पष्ट रूप से समझाना चाहिए। ट्रेड स्टडी का उद्देश्य किसी विशेष दृष्टिकोण को आगे बढ़ाने के बदले सर्वोत्तम समाधान तैयार करना है। कोई निष्कर्ष नहीं बताना, या यह निष्कर्ष निकालना पूरी तरह से स्वीकार्य है कि कोई भी विकल्प बदलाव की गारंटी देने के लिए आधार रेखा से पर्याप्त रूप से बहुत अच्छा नहीं है। इसे वैज्ञानिक प्रयास के रूप में देखा जाना चाहिए, न कि मार्केटिंग तकनीक के रूप में होता है।
एंटरप्राइज़ सॉफ़्टवेयर डेवलपमेंट में डिज़ाइन डाक्यूमेंटेशन का बहुत महत्वपूर्ण भाग डेटाबेस डिज़ाइन डाक्यूमेंटेशन (डीडीडी) है। इसमें वैचारिक, तार्किक और भौतिक डिज़ाइन तत्व सम्मिलित हैं। डीडीडी में वह विधिवत जानकारी सम्मिलित होती है जिसकी डेटाबेस के साथ इंटरैक्ट करने वाले लोगों को आवश्यकता होती है। इसे तैयार करने का उद्देश्य दृश्य के भीतर सभी खिलाड़ियों द्वारा उपयोग किए जाने वाला एक सामान्य स्रोत बनाना है। संभावित उपयोगकर्ता हैं:
- डेटाबेस डिज़ाइनर
- डेटाबेस डेवलपर
- डेटाबेस प्रशासक
- एप्लिकेशन डिज़ाइनर
- प्रोग्रामर
संबंध का डेटाबेस सिस्टम के बारे में बात करते समय, डाक्यूमेंटेशन में निम्नलिखित भाग सम्मिलित होने चाहिए:
- इकाई - रेलशनशिप स्कीमा (उन्नत इकाई-संबंध मॉडल या नहीं), जिसमें निम्नलिखित जानकारी और उनकी स्पष्ट परिभाषाएँ सम्मिलित हैं:
- इकाई सेट और उनकी विशेषताएँ
- रेलशनशिप और उनकी विशेषताएँ
- प्रत्येक इकाई सेट के लिए कैंडिडेट कुंजी
- विशेषता और टुपल आधारित बाधाएँ
- रिलेशन स्कीमा, जिसमें निम्नलिखित जानकारी सम्मिलित है:
- तालिकाएँ, विशेषताएँ और उनके गुण
- व्हियूज
- प्राथमिक कुंजी, विदेशी कुंजी जैसी बाधाएं,
- संदर्भात्मक बाधाओं की प्रमुखता
- संदर्भात्मक बाधाओं के लिए कैस्केडिंग नीति
- प्राथमिक कुंजी
व्हियूज में सभी अभिनेताओं द्वारा उपयोग की जाने वाली सभी जानकारी को सम्मिलित करना बहुत महत्वपूर्ण है। डाक्यूमेंटेशन को अपडेट करना इसलिए भी बहुत ज़रूरी है क्योंकि कोई भी बदलाव डेटाबेस में भी होता है।
तकनीकी डाक्यूमेंटेशन
सोर्स कोड (जिसमें रीडमी फ़ाइलें और एपीआई डाक्यूमेंटेशन सम्मिलित हो सकते हैं) से जुड़े कोड डाक्यूमेंटेशन का संपूर्ण होना ज़रूरी है, परन्तु इतना विस्तृत नहीं कि उन्हें बनाए रखना अत्यधिक समय लेने वाला या मुश्किल हो जाए। एपीआई लेखकों द्वारा प्रलेखित किए जा रहे सॉफ़्टवेयर एप्लिकेशन या सॉफ़्टवेयर प्रोडक्ट के लिए विभिन्न कैसे-कैसे और अवलोकन डाक्यूमेंटेशन मार्गदर्शिकाएँ सामान्यतौर पर विशिष्ट पाई जाती हैं। इस डाक्यूमेंटेशन का उपयोग डेवलपर्स, परीक्षको और एन्ड-यूजर द्वारा भी किया जा सकता है। आज, बिजली, ऊर्जा, परिवहन, नेटवर्क, एयरोस्पेस, सुरक्षा, सुरक्षा, उद्योग स्वचालन और कई अन्य डोमेन के क्षेत्रों में बहुत सारे उच्च-स्तरीय अनुप्रयोग देखे जाते हैं। ऐसे संगठनों के भीतर तकनीकी डाक्यूमेंटेशन महत्वपूर्ण हो गया है क्योंकि समय के साथ आर्टिटेक्चर में बदलाव के साथ जानकारी का आधारभूत और उन्नत स्तर बदल सकता है।
कोड डाक्यूमेंटेशन को अधिकांशतः संदर्भ गाइड शैली में व्यवस्थित किया जाता है, जिससे प्रोग्रामर को फ़ंक्शन या क्लास को तुरंत देखने की अनुमति मिलती है।
सोर्स कोड में एम्बेडेड तकनीकी डाक्यूमेंटेशन
डाक्यूमेंटेशन जनरेटर जैसे डॉक्सिजन, एनडॉक, व्हियूज एक्सपर्ट, जावाडोक, जेएसडॉक, एफिलस्टूडियो, सैंडकैसल (सॉफ्टवेयर), आरओबीओडॉक, ट्विनटेक्स्ट, या यूनिवर्सल रिपोर्ट का उपयोग कोड डाक्यूमेंटेशन को स्वचालित रूप से जेनरेट करने के लिए किया जा सकता है - अर्थात, वे जहां उपलब्ध हो, सोर्स कोड से टिप्पणियाँ और अनुबंध द्वारा डिज़ाइन निकालें और टेक्स्ट या एचटीएमएल फ़ाइलों जैसे रूपों में संदर्भ नियम बनाएं जाते हैं।
ऑटो-जनरेटिंग डाक्यूमेंटेशन का विचार विभिन्न कारणों से प्रोग्रामर के लिए आकर्षक है। उदाहरण के लिए, क्योंकि इसे सोर्स कोड से ही निकाला जाता है (उदाहरण के लिए, टिप्पणी (कंप्यूटर प्रोग्रामिंग) के माध्यम से), प्रोग्रामर इसे कोड का संदर्भ देते हुए लिख सकता है, और सोर्स कोड बनाने के लिए उपयोग किए जाने वाले समान टूल का उपयोग कर सकता है। इससे डाक्यूमेंटेशन को अद्यतन रखना बहुत सरल हो जाता है।
संभावित नकारात्मक पक्ष यह है कि केवल प्रोग्रामर ही इस प्रकार के डाक्यूमेंटेशन को संपादित कर सकते हैं, और आउटपुट को रिफ्रेश करना उन पर निर्भर करता है (उदाहरण के लिए, रात में डाक्यूमेंटेशन को अपडेट करने के लिए क्रॉन जॉब चलाकर)। कुछ लोग इसे हानि के वर्णन लाभ के स्तर पर प्रस्तुत करेंगे।
साक्षर प्रोग्रामिंग
सम्मानित कंप्यूटर वैज्ञानिक डोनाल्ड नुथ ने कहा है कि डाक्यूमेंटेशन एक बहुत ही कठिन विचार प्रक्रिया हो सकती है और उन्होंने साक्षर प्रोग्रामिंग के बारे में बताई गयी है, जो सोर्स कोड के समान समय और स्थान पर लिखी जाती है और स्वचालित माध्यमों से निकाली जाती है। प्रोग्रामिंग भाषाओं हास्केल (प्रोग्रामिंग भाषा) और कॉफ़ीस्क्रिप्ट में साक्षर प्रोग्रामिंग के सरल रूप के लिए अंतर्निहित समर्थन है, परन्तु इस समर्थन का व्यापक रूप से उपयोग नहीं किया जाता है।
व्याख्यात्मक प्रोग्रामिंग
व्याख्यात्मक प्रोग्रामिंग वास्तविक प्रोग्रामिंग संदर्भों में साक्षर प्रोग्रामिंग के व्यावहारिक अनुप्रयोगों का परिणाम है। व्याख्यात्मक प्रतिमान का प्रस्ताव है कि सोर्स कोड और डाक्यूमेंटेशन को अलग-अलग संग्रहीत किया जाना चाहिए।
अधिकांशतः, सॉफ़्टवेयर डेवलपर्स को ऐसी जानकारी बनाने और उस तक पहुंचने में सक्षम होने की आवश्यकता होती है जो सोर्स फ़ाइल का भाग नहीं होगी। इस तरह के टिप्पणी सामान्यतौर पर कई सॉफ्टवेयर डेवलपमेंट गतिविधियों का भाग होते हैं, जैसे कोड वॉक और पोर्टिंग, जहां तीसरे पक्ष के सोर्स कोड का कार्यात्मक तरीके से विश्लेषण किया जाता है। इसलिए एनोटेशन डेवलपर को सॉफ़्टवेयर विकास के किसी भी चरण के समय मदद कर सकता है जहां विधिवत डाक्यूमेंटेशन प्रणाली प्रगति में बाधा उत्पन्न करेगी।
उपयोगकर्ता डाक्यूमेंटेशन
कोड डाक्यूमेंटेशन के विपरीत, उपयोगकर्ता डाक्यूमेंटेशन केवल यह वर्णन करते हैं कि किसी प्रोग्राम का उपयोग कैसे किया जाता है।
लाइब्रेरी (कंप्यूटिंग) के अर्थ में, कोड डाक्यूमेंटेशन और उपयोगकर्ता डाक्यूमेंटेशन कुछ मामलों में प्रभावी रूप से समकक्ष और जुड़ने लायक हो सकते हैं, परन्तु सामान्य अनुप्रयोग के लिए यह अधिकांशतः सच नहीं होता है।
सामान्यतौर पर, उपयोगकर्ता डाक्यूमेंटेशन प्रोग्राम की प्रत्येक सुविधा का वर्णन करता है, और इन सुविधाओं को साकार करने में उपयोगकर्ता की सहायता करता है। उपयोगकर्ता डाक्यूमेंटेशन भ्रमित न हों और वे अद्यतित रहें, यह बहुत महत्वपूर्ण है। उपयोगकर्ता डाक्यूमेंटेशन को किसी विशेष तरीके से व्यवस्थित करने की आवश्यकता नहीं है, परन्तु उनके लिए संपूर्ण अनुक्रमणिका (प्रकाशन) होना बहुत महत्वपूर्ण है। संगति और सरलता भी बहुत मूल्यवान हैं। उपयोगकर्ता डाक्यूमेंटेशन को अनुबंध माना जाता है जो निर्दिष्ट करता है कि सॉफ़्टवेयर क्या करेगा। एपीआई लेखक अच्छे उपयोगकर्ता डाक्यूमेंटेशन लिखने में बहुत अच्छे हैं क्योंकि वे उपयोग की जाने वाली सॉफ़्टवेयर आर्टिटेक्चर और प्रोग्रामिंग तकनीकों से अच्छी तरह परिचित होंगे। तकनीकी लेखन भी देखना है।
उपयोगकर्ता डाक्यूमेंटेशन विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।[1] चूँकि, तीन व्यापक तरीके हैं जिनसे उपयोगकर्ता डाक्यूमेंटेशन को व्यवस्थित किया जा सकता है।
- ट्यूटोरियल: नए उपयोगकर्ता के लिए ट्यूटोरियल दृष्टिकोण सबसे उपयोगी माना जाता है, जिसमें उन्हें विशेष कार्यों को पूरा करने के प्रत्येक चरण के माध्यम से निर्देशित किया जाता है।[2]
- थमेटिक: थीम (साहित्य) दृष्टिकोण, जहां अध्याय या अनुभाग रुचि के एक विशेष क्षेत्र पर ध्यान केंद्रित करते हैं, मध्यवर्ती उपयोगकर्ता के लिए अधिक सामान्य उपयोग का होता है। कुछ लेखक उपयोगकर्ता की ज़रूरतों को पूरा करने के लिए ज्ञान आधारित लेख के माध्यम से अपने विचार व्यक्त करने में रूचि करते हैं। यह दृष्टिकोण सामान्यतौर पर सूचना प्रौद्योगिकी जैसे गतिशील उद्योग द्वारा अपनाया जाता है।[3]
- लिस्ट या रिफरेन्स: अंतिम प्रकार का आयोजन सिद्धांत वह है जिसमें आदेशों या कार्यों को केवल वर्णानुक्रम में या तार्किक रूप से समूहीकृत किया जाता है, अधिकांशतः क्रॉस-रेफर्ड इंडेक्स के माध्यम से किया जाता है। यह बाद वाला दृष्टिकोण उन उन्नत उपयोगकर्ताओं के लिए अधिक उपयोगी है जो जानते हैं कि वे किस प्रकार की जानकारी की इच्छा कर रहे हैं।
सॉफ़्टवेयर डाक्यूमेंटेशन के संबंध में उपयोगकर्ताओं के बीच सरल उलाहना यह है कि इन तीन दृष्टिकोणों में से केवल एक को अन्य दो से लगभग बाहर कर दिया गया है। व्यक्तिगत कंप्यूटरों के लिए प्रदान किए गए सॉफ़्टवेयर डाक्यूमेंटेशन को ऑनलाइन सहायता तक सीमित करना आम बात है जो केवल कमांड या मेनू आइटम पर संदर्भ जानकारी देते हैं। नए उपयोगकर्ताओं को प्रशिक्षित करने या अधिक अनुभवी उपयोगकर्ताओं को किसी कार्यक्रम से अधिकतम लाभ प्राप्त करने में मदद करने का काम निजी प्रकाशकों पर छोड़ दिया गया है, जिन्हें अधिकांशतः सॉफ़्टवेयर डेवलपर द्वारा महत्वपूर्ण सहायता दी जाती है।
उपयोगकर्ता डाक्यूमेंटेशन तैयार करना
तकनीकी डाक्यूमेंटेशन के अन्य रूपों की तरह, अच्छे उपयोगकर्ता डाक्यूमेंटेशन को विकास की संगठित प्रक्रिया से लाभ मिलता है। उपयोगकर्ता डाक्यूमेंटेशन के अर्थ में, उद्योग में सामान्यतौर पर होने वाली प्रक्रिया में पाँच चरण होते हैं:[4]
- उपयोगकर्ता विश्लेषण, प्रक्रिया का मूल अनुसंधान चरण है।[5]
- योजना, या वास्तविक डाक्यूमेंटेशन चरण है।[6]
- ड्राफ्ट समीक्षा, आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।[7]
- प्रयोज्यता परीक्षण, जिसके द्वारा डाक्यूमेंटेशन की प्रयोज्यता का अनुभवजन्य परीक्षण किया जाता है।[8]
- संपादन, अंतिम चरण जिसमें चरण तीन और चार में एकत्र की गई जानकारी का उपयोग अंतिम प्रारूप तैयार करने के लिए किया जाता है।
प्रलेखन और त्वरित विकास विवाद
डेवलपर्स के बीच डाक्यूमेंटेशन का विरोध सर्वविदित है और इस पर जोर देने की आवश्यकता नहीं है।[9] यह स्थिति विशेष रूप से अगिल सॉफ्टवेयर डेवलपमेंट में प्रचलित है क्योंकि ये पद्धतियाँ किसी भी अनावश्यक गतिविधियों से बचने की कोशिश करती हैं जो सीधे तौर पर मूल्य नहीं लाती हैं।
विशेष रूप से, द एजाइल मेनिफेस्टो व्यापक डाक्यूमेंटेशन की तुलना में सॉफ़्टवेयर डेवलपमेंट को महत्व देने के बारे में बताता है, जिसकी व्याख्या निंदनीय रूप से की जा सकती है क्योंकि हम अपना सारा समय कोडिंग में बिताना चाहते हैं। याद रखें, वास्तविक प्रोग्रामर डाक्यूमेंटेशन नहीं लिखते हैं।[10] चूँकि, सॉफ्टवेयर इंजीनियरिंग विशेषज्ञों के बीच सर्वेक्षण से पता चला है कि त्वरित विकास में डाक्यूमेंटेशन को किसी भी तरह से अनावश्यक नहीं माना जाता है। फिर भी यह स्वीकार किया जाता है कि विकास में प्रेरक समस्याएं हैं, और त्वरित विकास के अनुरूप डाक्यूमेंटेशन विधियों (उदाहरण के लिए रेपिटूशन सिस्टम और गामिफिकेशन के माध्यम से) की आवश्यकता हो सकती है।[11][12]
विपणन दस्तावेज़
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को प्रोडक्ट के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। डाक्यूमेंटेशन के इस रूप के तीन उद्देश्य हैं:
- संभावित उपयोगकर्ता को प्रोडक्ट के बारे में उत्साहित करना और उनमें इसके साथ और अधिक जुड़ने की इच्छा उत्पन्न करना होता है।
- उन्हें इस बारे में सूचित करना कि प्रोडक्ट वास्तव में क्या करता है, जिससे कि उनकी अपेक्षाएं उन्हें प्राप्त होने वाली चीज़ों के अनुरूप हों।
- अन्य विकल्पों के संबंध में इस प्रोडक्ट की स्थिति स्पष्ट करना हो।
यह भी देखें
- एपीआई राइटर
- डाक्यूमेंटेशन जनरेटर की तुलना
- अनुबंध द्वारा डिज़ाइन
- डिज़ाइन डाक्यूमेंटेशन
- डॉकस्ट्रिंग
- डाक्यूमेंटेशन
- साक्षर प्रोग्रामिंग
- रेडमी फाइल
- उपयोगकर्ता सहायता
- एकीकृत मॉडलिंग लैंग्वेज यूएमएल
टिप्पणियाँ
- ↑ "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)".
- ↑ Woelz, Carlos. "The KDE Documentation Primer". Retrieved 15 June 2009.
- ↑ Microsoft. "Knowledge Base Articles for Driver Development". Microsoft. Retrieved 15 June 2009.
- ↑ 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
- ↑ Barker, pg. 118.
- ↑ Barker, pg. 173.
- ↑ Barker, pg. 217.
- ↑ Barker, pg. 240.
- ↑ Herbsleb, James D. and Moitra, Dependra. In: IEEE Software, vol. 18, no. 2, pp. 16-20, Mar/Apr 2001
- ↑ Rakitin, Steven. , "Manifesto elicits cynicism." IEEE Computer, vol. 34, no. 12, p. 4, 2001
- ↑ 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.
- ↑ Selic, Bran. "Agile documentation, anyone?" In: IEEE Software, vol. 26, no. 6, pp. 11-12, 2009
