ऐसी बग रिपोर्ट बोलकर कैसे लिखें जिसे कोई और दोहरा सके

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

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

शुरुआत खराबी से करें, निदान से नहीं

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

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

GitHub की इश्यू बनाने की मार्गदर्शिका वर्णनात्मक शीर्षक और विवरण लिखने की बात करती है और बताती है कि रिपॉज़िटरी में इश्यू टेम्पलेट हो सकता है। अगर टेम्पलेट है, तो उसे इस्तेमाल करें। नीचे दिया गया बोलकर लिखने का ढाँचा उसके फ़ील्ड भरने से पहले तथ्य जुटाने में मदद करता है; यह प्रोजेक्ट के अपने निर्देशों को अनदेखा करने का कारण नहीं है।

पाँच फ़ील्ड वाला वॉइस नोट

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

1. संदर्भ: आप क्या करने की कोशिश कर रहे थे? पेज, सुविधा या कार्रवाई का नाम बताएँ।
2. चरण: किन कार्रवाइयों से खराबी हुई? उन्हें क्रम से नंबर दें।
3. अपेक्षित: आप उचित रूप से किस परिणाम की उम्मीद कर रहे थे?
4. वास्तविक: स्क्रीन पर क्या हुआ? छोटी त्रुटि को जाँचने के बाद ही उद्धृत करें।
5. दायरा: यह कब और किस परिवेश में हुआ, और क्या आप इसे दोहरा सकते हैं?

यहाँ कॉपी-पेस्ट करने योग्य टेम्पलेट है। हर वर्ग कोष्ठक की जगह देखा हुआ विवरण लिखें। अगर कोई फ़ील्ड अज्ञात है, तो संभावित जवाब भरने के बजाय “जाँच नहीं की” लिखें।

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

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

एक बार दोहराएँ, फिर क्लिकों का क्रम बताएँ

याददाश्त घटनाओं के क्रम को सारांश में बदल देती है। “मैंने एक सेटिंग बदली और पेज क्रैश हो गया” में रिफ़्रेश, अकाउंट बदलना या बिना सहेजा फ़ॉर्म छूट सकता है। अगर सुरक्षित हो, तो प्रभावित ऐप के बगल में ड्राफ़्ट खोलकर वही क्रम दोहराएँ। हर कार्रवाई के बाद रुकें और दर्ज करें कि आपने क्या किया। केवल शब्द बेहतर करने के लिए डेटा मिटाने या पैसे काटने वाले बग को बार-बार सक्रिय न करें।

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

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

अपेक्षित और वास्तविक परिणाम अलग रखें

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

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

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

परिवेश बताएँ, लेकिन अनावश्यक विस्तृत जाँच-फ़ाइल न बनाएँ

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

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

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

दर्ज करने से पहले दो चरणों में संपादन करें

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

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

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

अक्सर पूछे जाने वाले प्रश्न

क्या मैं बग रिपोर्ट लिखने के लिए बोलकर लिखने की सुविधा इस्तेमाल कर सकता/सकती हूँ?

हाँ। संदर्भ, दोहराने के चरण और अपेक्षित तथा वास्तविक व्यवहार को निजी ड्राफ़्ट में बोलकर लिखें। साझा करने से पहले सटीक कमांड, त्रुटि संदेश, URL और संस्करण संख्याएँ टाइप करके जाँच लें।

बग रिपोर्ट में क्या शामिल होना चाहिए?

वर्णनात्मक शीर्षक, शुरुआती संदर्भ, क्रमबद्ध चरण, अपेक्षित परिणाम, वास्तविक परिणाम, संबंधित परिवेश और ज़रूरत होने पर सुरक्षित सबूत शामिल करें। रिपॉज़िटरी में इश्यू टेम्पलेट हो तो उसका पालन करें।

जिस बग को मैं दोहरा नहीं सकता/सकती, उसकी रिपोर्ट कैसे करूँ?

बताएँ कि यह एक बार हुआ या कभी-कभी होता है, आपने जो देखा और जिस परिवेश के बारे में जानते हैं उसे दर्ज करें, और बताएँ कि किन प्रयासों में इसे दोहराया नहीं जा सका। अज्ञात चरणों में अनुमान न भरें।

क्या मुझे सार्वजनिक इश्यू में लॉग संलग्न करने चाहिए?

केवल तब, जब आपने उनमें गोपनीय सामग्री और व्यक्तिगत जानकारी की जाँच कर ली हो। संवेदनशील डेटा हटाएँ या ढकें और खराबी समझाने में मदद करने वाला सबसे छोटा अंश साझा करें। अपनी टीम के घटना प्रबंधन और गोपनीयता नियमों का पालन करें।

Talkpad मुफ़्त डाउनलोड करें – मुफ़्त प्लान में 2,500 शब्द/सप्ताह।