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

From Vigyanwiki
No edit summary
No edit summary
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Short description|Explains the functionality of software}}
{{Short description|Explains the functionality of software}}
{{more citations needed|date=March 2013}}
'''[[सॉफ़्टवेयर|सॉफ़्टवेयर डाक्यूमेंटेशन]]''' लिखित टेक्स्ट या स्पष्टीकरण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। डाक्यूमेंटेशन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है।
[[सॉफ़्टवेयर|सॉफ़्टवेयर प्रलेखन]] लिखित पाठ या चित्रण है जो कंप्यूटर सॉफ़्टवेयर के साथ आता है या स्रोत कोड में एम्बेडेड होता है। प्रलेखन या तो यह बताता है कि सॉफ़्टवेयर कैसे संचालित होता है या इसका उपयोग कैसे किया जाता है, और विभिन्न भूमिकाओं में लोगों के लिए इसका अर्थ अलग-अलग हो सकता है।


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


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


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


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


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


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


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


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


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


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


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


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


== तकनीकी दस्तावेज ==
== तकनीकी डाक्यूमेंटेशन   ==


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


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


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


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


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


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


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


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


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


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


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


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


उपयोगकर्ता दस्तावेज़ीकरण विभिन्न प्रकार के ऑनलाइन और प्रिंट प्रारूपों में तैयार किया जा सकता है।<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  
   | title = The KDE Documentation Primer
   | title = The KDE Documentation Primer
   | url = http://i18n.kde.org/docs/doc-primer/index.html
   | url = http://i18n.kde.org/docs/doc-primer/index.html
   | access-date = 15 June 2009 }}</ref> # विषयगत: एक [[थीम (साहित्य)]] दृष्टिकोण, जहां अध्याय या अनुभाग रुचि के एक विशेष क्षेत्र पर ध्यान केंद्रित करते हैं, एक मध्यवर्ती उपयोगकर्ता के लिए अधिक सामान्य उपयोग का होता है। कुछ लेखक उपयोगकर्ता की ज़रूरतों को पूरा करने के लिए ज्ञान आधारित लेख के माध्यम से अपने विचार व्यक्त करना पसंद करते हैं। यह दृष्टिकोण आमतौर पर सूचना प्रौद्योगिकी जैसे गतिशील उद्योग द्वारा अपनाया जाता है।<ref name=kbad>{{cite web
   | access-date = 15 June 2009 }}</ref>  
#'''थमेटिक''': [[थीम (साहित्य)]] दृष्टिकोण, जहां अध्याय या अनुभाग रुचि के एक विशेष क्षेत्र पर ध्यान केंद्रित करते हैं, मध्यवर्ती उपयोगकर्ता के लिए अधिक सामान्य उपयोग का होता है। कुछ लेखक उपयोगकर्ता की ज़रूरतों को पूरा करने के लिए ज्ञान आधारित लेख के माध्यम से अपने विचार व्यक्त करने में रूचि करते हैं। यह दृष्टिकोण सामान्यतौर पर सूचना प्रौद्योगिकी जैसे गतिशील उद्योग द्वारा अपनाया जाता है।<ref name="kbad">{{cite web
   | last = Microsoft
   | last = Microsoft
   | author-link = Microsoft
   | author-link = Microsoft
Line 95: Line 96:
   | access-date = 15 June 2009 }}
   | access-date = 15 June 2009 }}
</ref>
</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. 173.</ref>
# ड्राफ्ट समीक्षा, एक आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।<ref>Barker, pg. 217.</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>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>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. 173.</ref>
# ड्राफ्ट समीक्षा, आत्म-व्याख्यात्मक चरण जहां पिछले चरण में तैयार किए गए ड्राफ्ट पर प्रतिक्रिया मांगी जाती है।<ref>Barker, pg. 217.</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>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>
==विपणन दस्तावेज़ ==
==विपणन दस्तावेज़ ==
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को उत्पाद के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। दस्तावेज़ीकरण के इस रूप के तीन उद्देश्य हैं:
कई अनुप्रयोगों के लिए आकस्मिक पर्यवेक्षकों को प्रोडक्ट के बारे में सीखने में अधिक समय बिताने के लिए प्रोत्साहित करने के लिए कुछ प्रचार सामग्री का होना आवश्यक है। डाक्यूमेंटेशन के इस रूप के तीन उद्देश्य हैं:


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


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


== टिप्पणियाँ ==
== टिप्पणियाँ ==
{{Reflist}}
{{Reflist}}


{{Software engineering}}
{{DEFAULTSORT:Software Documentation}}
 
{{DEFAULTSORT:Software Documentation}}[[Category: सॉफ़्टवेयर दस्तावेज़ीकरण| सॉफ़्टवेयर दस्तावेज़ीकरण]] [[Category: तकनीकी संचार]] [[Category: तकनीकी संचार]] [Category:Technical communicati
 


[[Category: Machine Translated Page]]
[[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] चूँकि, तीन व्यापक तरीके हैं जिनसे उपयोगकर्ता डाक्यूमेंटेशन को व्यवस्थित किया जा सकता है।

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

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

उपयोगकर्ता डाक्यूमेंटेशन तैयार करना

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

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

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

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

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