क्या वास्तव में 'प्रलेखन' शामिल हैं?

Question

जब हम किसी सॉफ्टवेयर उत्पाद के लिए 'प्रलेखन' कहते हैं, तो उसमें क्या शामिल है और क्या नहीं होना चाहिए?

उदाहरण के लिए, हाल ही में एक प्रश्न पूछा गया कि क्या टिप्पणियों को प्रलेखन माना जाता है?

लेकिन कई अन्य क्षेत्र हैं जो यह एक वैध प्रश्न है, साथ ही कुछ दूसरों की तुलना में अधिक स्पष्ट है:

• मैनुअल (स्पष्ट रूप से)
• रिलीज नोट्स?
• ट्यूटोरियल
• टिप्पणियाँ
• अन्य कोई?

रेखा कहां खींची गई है। उदाहरण के लिए, यदि 'ट्यूटोरियल' दस्तावेज़ीकरण है, तो 'वीडियो ट्यूटोरियल' प्रलेखन है, या यह कुछ और है?

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

---

_{हमारे सम्मेलन में हाल की ग्राहक प्रतिक्रिया से प्रश्न प्रेरित करता है कि यह दर्शाता है कि हमारे डॉक्टर को और अधिक 'नमूनों' की आवश्यकता थी, जिसे हम पहले से विचार करने में उतना अच्छा नहीं था जितना कि हमें होना चाहिए था।}

_{श्रोता: हमारे डेटाबेस (प्रोग्रामिंग), प्रोग्रामिंग लैंग्वेज और संबंधित टूलिंग का उपयोग करने वाले सॉफ्टवेयर डेवलपर (जैसे कि कहा गया डीबी के लिए एडमिन क्लाइंट)}

Comments

चढ़ाव पर टिप्पणियाँ हमेशा की सराहना की। दुर्भाग्य से संख्या यह समझने के लिए अधिक रचनात्मक आलोचना प्रदान नहीं करती है कि कोई कहां भटक गया है :)

— दान मैकग्राथ

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

— यनीस

संबंधित: क्या टिप्पणियाँ दस्तावेज़ीकरण का एक रूप हैं

— डायनेमिक

यह प्रश्न किसी के लिए वेन आरेख खींचने के लिए चिल्ला रहा है।

— मैथअटैक

Answer 1

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

लक्ष्य (सॉफ्टवेयर को समझाते हुए) को ध्यान में रखते हुए, प्रलेखन समाप्त हो जाता है जब ग्राहक स्पष्टीकरण से संतुष्ट होता है : जिस तरह से सॉफ्टवेयर के संतुष्ट होने पर ग्राहक समाप्त होता है। ध्यान रखें कि प्रलेखन के लिए ग्राहक हमेशा सॉफ्टवेयर के लिए भुगतान करने वाले ग्राहक के समान नहीं होता है: समर्थन कर्मी, परीक्षक, salespeople और अन्य सभी को कुछ समझ की आवश्यकता होगी कि सॉफ्टवेयर क्या करता है और यह कैसे काम करता है।

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

Comments

यदि सॉफ़्टवेयर का उत्पादन किया जाता है, तो मैं केवल पाठ्यक्रम सामग्री को दस्तावेज़ीकरण मानता हूँ, यदि वे उसी टीम द्वारा (व्यापक अर्थ में) उत्पादित / वितरित की जा रही हों। पूरी तरह से तृतीय-पक्ष पाठ्यक्रम डॉक्स नहीं हैं।

— डोनल फेलो

बेशक वे कर रहे हैं। थर्ड-पार्टी डॉक्यूमेंटेशन डॉक्यूमेंटेशन है, भले ही यह आपके नियंत्रण में नहीं है (और आपके उत्पादन की जिम्मेदारी नहीं है): यह उन्हें सामान समझाने के पाठक के लक्ष्य को पूरा करता है। यदि यह आपके लिए एक समस्या है कि लोग ऐसे दस्तावेज़ लिख रहे हैं जो आपके नियंत्रण में नहीं हैं, तो आपको उस दस्तावेज़ की आवश्यकता को कम करना चाहिए।

Answer 2

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

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

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

कुछ कारक जो खेल में आएंगे:

• क्या आप सॉफ्टवेयर v1.0 विकसित कर रहे हैं और वे अन्य परियोजनाओं पर आगे बढ़ रहे हैं या यह ऑन-गोइंग, लॉन्ग टर्म प्रोजेक्ट है? उत्तरार्द्ध मामले में टिप्पणियाँ / डिज़ाइन डॉक्स अधिक महत्वपूर्ण हो जाते हैं। दूसरी तरफ यदि आपका ग्राहक एक माँ-और-पॉप डोनट की दुकान है और आप उनके लिए एक वेबसाइट लिख रहे हैं जो आप कभी नहीं देखेंगे ... तो मुझे लगता है कि कोड प्रलेखन अच्छा है, लेकिन यह महत्वपूर्ण नहीं है।
• क्या आप एक मोबाइल गेम या सॉफ्टवेयर विकसित कर रहे हैं जो अस्पताल में हृदय गति की निगरानी को नियंत्रित कर रहा है। लगता है कि जो एक "किया" की परिभाषा है कि बहुत अधिक प्रलेखन है?
• क्या आपके ग्राहक विशिष्ट उपयोगकर्ता हैं या वे अन्य डेवलपर हैं? क्या आपके पास एक एपीआई / एसडीके है जिसे आप उजागर कर रहे हैं?
• आपके ग्राहकों की विशेषज्ञता का स्तर क्या है? यह वीडियो ट्यूटोरियल बनाम लिखित सामग्री बनाम किसी प्रकार के इंटरैक्टिव ट्यूटोरियल ऐप की पसंद को प्रभावित करता है
• क्या आपके ग्राहक इस बात की परवाह करते हैं कि संस्करण से संस्करण में क्या परिवर्तन हुआ है। कुछ करते हैं। ज्यादातर नहीं। कुछ के लिए यह कानून (या उस के करीब) देखभाल करने के लिए है।

Comments

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

— डैन मैकग्राथ

@DanMcGrath: क्षमा करें, मैं अपने स्वयं के, गलत तरीके से, सहित पीएम को रगड़ने की कोशिश कर रहा हूं :) भले ही मुझे आपके क्यू से आकर्षित किया गया निष्कर्ष के बावजूद, मैं अभी भी बनाए रखूंगा कि कोड के साथ जाने वाली "कुछ भी" पर विचार किया जा सकता है "प्रलेखन"। अगर मैं आपसे "क्या दस्तावेज हो सकता है" यह पूछने के बजाय और सभी प्रकार की चीजों की एक व्यापक सूची संकलित करता था (मैं उस पर एक यूएमएल आरेख के साथ एक संदर्भ नैपकिन रखता था), मैं अपने ग्राहक आधार पर वापस जाऊंगा और पूछूंगा उन्हें जो चाहिए। अगर कोई यह नहीं कहता कि "मुझे एक वीडियो ट्यूटोरियल चाहिए", तो मैं उस पर विचार करके भी कोई मस्तिष्क चक्र क्यों खर्च करूंगा?

— DXM

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

— डैन मैकग्राथ

Answer 3

दस्तावेज़ीकरण सामान है इसे पढ़ने के बिना संशोधित करने का इरादा है।

मुझे लगता है कि आप उद्देश्य-आधारित परिभाषा के साथ गलत नहीं हो सकते ... लेकिन केवल अगर आप उद्देश्य को ठीक से परिभाषित करते हैं।

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

के लिए 'नमूने' प्रदान करने के लिए जा रहे हैं, पढ़ने के लिए नहीं-संशोधित भेद काफी महत्वपूर्ण बन सकता है।

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

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

Answer 4

कुछ भी जो "मैं कैसे करूं ..." का उत्तर है, प्रश्न प्रलेखन है।

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

उपयोगकर्ताओं के लिए, इसका मतलब है कि उपयोगकर्ता पुस्तिकाएं ("मैं सॉफ्टवेयर का उपयोग कैसे करूं"), ट्यूटोरियल ("मैं इस विशिष्ट सुविधा का उपयोग कैसे करूं"), नोट्स जारी करें ("मुझे कैसे पता चलेगा कि क्या कीड़े तय हो गए हैं / नई बग विशेषताएं हैं) जोड़ा "), आदि।