सॉफ्टवेयर डेवलपमेंट डॉक्यूमेंटेशन

परिचय

शुभ दोपहर, प्रिय समुदाय।
मुझे अपना परिचय दो। मैं एक व्यापार विश्लेषक हूं, मैं दस साल से कस्टम सॉफ्टवेयर डेवलपमेंट के क्षेत्र में काम कर रहा हूं, हाल ही में मैं एक विश्लेषक और एक प्रोजेक्ट मैनेजर की भूमिकाओं का संयोजन कर रहा हूं।

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

इसलिए, शुरुआत के लिए, मैं मुख्य प्रश्न का उत्तर दूंगा: यह सब किस लिए है?
इसके कई कारण हैं।

1. प्रलेखन परियोजना के लिए एक "सामान्य स्थान" प्रदान करता है। किसी भी समय कोई भी प्रतिभागी किसी विशिष्ट कार्य और कार्य की सामान्य दिशा दोनों पर आवश्यक जानकारी प्राप्त कर सकता है।
2. टीम "एक भाषा में" कहती है - "किसी मामले में गूंगे बग के बारे में" जो कि एक महीने पहले वास्या ने किया था। "
3. प्रलेखन आपको परियोजना के प्रतिभागियों के बीच जिम्मेदारी के क्षेत्रों के बीच स्पष्ट रूप से अंतर करने की अनुमति देता है।
4. केवल सावधानीपूर्वक वर्णित आवश्यकताओं को पूर्णता और स्थिरता के लिए जांचा जा सकता है। "दायर किए गए नोट" यह सुनिश्चित करने के लिए एक सीधा और बहुत तेज़ तरीका है कि परियोजना की सीमाएं कर्कश तिलचट्टों द्वारा फैली हुई हैं, और शुरुआत में कल्पना की गई कार्यक्षमता प्रक्रिया में उत्पन्न होने वाली ग्राहक की "इच्छाओं" के साथ नहीं बढ़ेगी।

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

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

मैं एक सम्मानित समुदाय की अदालत में एक प्रलेखन योजना का प्रस्ताव करता हूं जो मुझे सुविधाजनक, तार्किक और सही लगती है। और - हाँ, यह काम करता है।

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

1. संदर्भ की शर्तें।
2. संदर्भ की निजी शर्तें (वैकल्पिक)।
3. केस का उपयोग करें।
4. परीक्षण परिदृश्य (टेस्ट केस)।
5. बग रिपोर्ट।
6. उपयोगकर्ता मैनुअल।
7. प्रशासक मैनुअल (वैकल्पिक)।

नीचे दिया गया आंकड़ा इन दस्तावेजों के बीच संबंध का एक चित्र है।


यह कैसे काम करता है?

टी

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

CTZ

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

मामले का उपयोग करें

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

टेस्ट केस

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

बग की रिपोर्ट

मैं थोड़ा और अधिक टोपीदार हो जाऊंगा: बग रिपोर्ट सिस्टम के परीक्षण की प्रक्रिया में होती है जो त्रुटि के लिए परीक्षक की प्रतिक्रिया के रूप में होती है। प्रत्येक दस्तावेज़ को आवश्यक रूप से संबंधित टेस्ट केस को संदर्भित करना चाहिए।
दस्तावेज़ में होना चाहिए:
• त्रुटि के स्क्रीनशॉट;
• पिछले कार्यों का विवरण। ऐसे विवरण के लिए एक टेम्पलेट विकसित करना सबसे अच्छा है जो सभी के लिए सुविधाजनक है - यह बग को पुन: पेश करते समय डेवलपर्स के समय की बहुत बचत करता है;
• त्रुटि का शाब्दिक विवरण।

उपयोगकर्ता गाइड / प्रशासक गाइड

लिखने के लिए सबसे उबाऊ, लेकिन, फिर भी, महत्वपूर्ण दस्तावेज।
वास्तव में, उनके गठन को स्वचालित भी किया जा सकता है यदि सभी परीक्षण मामलों और उपयोग मामलों को उचित परिश्रम और सही ढंग से प्रारूपित के साथ लिखा गया हो।
मैं उन पर विस्तार से ध्यान नहीं दूंगा, यदि विषय मेरे लिए रुचि का है, तो मैं इस बारे में बात करूंगा कि वे कैसे स्वचालित हो सकते हैं।

निष्कर्ष

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