कैसे एक docs टीम ने खुद पेज पर पूछकर सही पेजों को ठीक किया

एक open-source प्रोजेक्ट में अच्छी डॉक्यूमेंटेशन है और एक वास्तविक समस्या भी: इंस्टॉलेशन गाइड थोड़ी सी गलत है। दो रिलीज़ पहले एक स्टेप बदल गया था, और अब नए लोग उसी जगह फंस जाते हैं। लोग ध्यान देते हैं — सोशल मीडिया पर शिकायतें होती हैं और कम्युनिटी चैट में कुछ उलझे हुए सवाल होते हैं — लेकिन मेंटेनर्स (maintainers) इस पर कोई कार्रवाई नहीं कर सकते, क्योंकि कोई भी शिकायत यह नहीं बताती कि **कौन सा पेज**। "आपकी डॉक्यूमेंटेशन आउट ऑफ डेट है" एक भावना है, बग रिपोर्ट नहीं। इसलिए वह गलत स्टेप महीनों तक वहीं रहता है, और शुरुआत करने की कोशिश करने वाले हर नए यूज़र को चुपचाप दूर कर देता है। डॉक्यूमेंटेशन का जीवन इस लूप पर निर्भर करता है: एक पाठक किसी भ्रमित करने वाले या गलत हिस्से पर पहुंचता है, मेंटेनर्स को ठीक से बताता है कि वह कहां है, और मेंटेनर्स उसे ठीक कर देते हैं। "ठीक से कहां" वाले हिस्से को तोड़ दें, तो पूरा लूप रुक जाता है。 ## समस्या: बिना लोकेशन का फीडबैक सिर्फ शोर है पाठक मदद करने के इच्छुक होते हैं। वे खुशी-खुशी आपको बताएंगे कि कोई पेज भ्रमित करने वाला है। लेकिन जो वे नहीं करेंगे, वह उस मदद को कार्रवाई योग्य बनाने के लिए आवश्यक खोजबीन है — URL कॉपी करना, सही संपर्क चैनल ढूंढना, समस्या का वर्णन करना, और यह नोट करना कि कौन सा सेक्शन और कौन सा वर्ज़न। किसी ऐसे व्यक्ति के लिए जो आपका टूल सीखने की कोशिश कर रहा है, न कि आपके docs का ऑडिट करने की, यह बहुत सारे स्टेप्स हैं。 इसलिए जो फीडबैक पहुंचता है, उसमें वह एक चीज़ गायब होती है जो उसे उपयोगी बनाती है: लोकेशन। "API docs गलत हैं" पढ़ने वाले एक मेंटेनर के पास सैकड़ों पेज होते हैं और उसे कोई अंदाजा नहीं होता कि कहां देखना है। एक GitHub issue मदद करता है, लेकिन इसके लिए एक साधारण पाठक को अकाउंट बनाना पड़ता है, आपके issue टेम्पलेट को समझना पड़ता है, और docs से पूरी तरह बाहर जाकर कॉन्टेक्स्ट बदलना पड़ता है — यह एक ऐसी रुकावट है जो अधिकतर चलते-फिरते मिलने वाले फीडबैक को रोक देती है, जो वास्तव में ऐसा फीडबैक होता है जो छोटी लेकिन अधिक प्रभाव वाली गलतियों को पकड़ता है。 नतीजा एक अजीब असंतुलन है: बहुत सारे पाठक समस्याएं देखते हैं, लेकिन लगभग कोई भी ऐसे रूप में रिपोर्ट नहीं किया जाता जिसे आप ठीक कर सकें。 ## समाधान: हर पेज पर एक "Report an issue" लिंक हर docs पेज के फुटर में एक छोटा **Report an issue with this page** लिंक डालें। यह एक `mailto:` लिंक होता है, और इसकी खूबी यह है कि यह विषय और मुख्य भाग में वर्तमान पेज के पथ को पहले से भर देता है। पाठक क्लिक करता है, उसका ईमेल पहले से ही कैप्चर की गई लोकेशन के साथ खुलता है, और वे केवल यह जोड़ते हैं कि क्या गलत था。 चूंकि docs आमतौर पर टेम्पलेट या स्टैटिक-साइट जनरेटर से बनाए जाते हैं, आप पथ को स्वचालित रूप से डाल सकते हैं। एक टेम्पलेट वाली साइट में, पेज वेरिएबल को सीधे लिंक में डाल दें: ```html <a href="mailto:[email protected]?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> इस पेज के साथ कोई समस्या रिपोर्ट करें </a> ``` या इसे एक लाइन की स्क्रिप्ट के साथ सेट करें ताकि यह बिना टेम्पलेटिंग के किसी भी पेज पर काम करे: ```html <a id="docs-issue" href="#">इस पेज के साथ कोई समस्या रिपोर्ट करें</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` इस साइट का जनरेटर एन्कोडेड लिंक बनाता है; स्क्रिप्ट केवल लाइव पथ को बदलती है। अब हर रिपोर्ट के विषय में सटीक पेज का नाम होता है, और मेंटेनर सीधे स्रोत फ़ाइल पर जा सकता है。 ## इसके लिए ऑन-पेज (on-page), इश्यू ट्रैकर (issue tracker) से बेहतर क्यों है इश्यू ट्रैकर किसी समाधान के लिए सही जगह है, लेकिन फीडबैक के लिए एक खराब प्रवेश द्वार है। यह एक अकाउंट, कॉन्टेक्स्ट बदलने, और आपकी प्रक्रिया से परिचित होने की मांग करता है — ऐसी बाधाएं जो उस साधारण पाठक को वापस भेज देती हैं जिसने अभी-अभी एक कोड सैंपल में टाइपिंग की गलती देखी है। `mailto:` लिंक पाठकों से वहीं मिलता है जहां असल में भ्रम पैदा होता है: पेज पर, एक क्लिक में, बिना किसी अकाउंट के। यह उन छोटे सुधारों की लंबी शृंखला को कैप्चर करता है जो कभी भी ट्रैकर तक नहीं पहुंच पाते。 ये दोनों एक साथ अच्छी तरह काम करते हैं। रिपोर्ट ईमेल से आती हैं, जो पहले से ही पेज के साथ टैग की गई होती हैं; एक मेंटेनर उन्हें छांटता है और ट्रैकर में केवल उन्हीं के लिए इश्यू खोलता है जिन्हें ट्रैक करने की आवश्यकता होती है। आपको सामने की तरफ ईमेल की कम रुकावट और पीछे की तरफ ट्रैकर की कठोरता मिलती है。 ## इसे सेट अप करना 1. एक docs इनबॉक्स चुनें जैसे `docs@` जिस पर मेंटेनर्स नज़र रखते हों। 2. जनरेटर में, प्राप्तकर्ता, 'Docs issue: [पेज का पथ]' का विषय, और एक मुख्य भाग सेट करें जो पूछता हो कि क्या गलत है और क्या मदद करेगा। 3. अपने पेज टेम्पलेट के फुटर में लिंक जोड़ें, अपने जनरेटर के पेज वेरिएबल या ऊपर दी गई छोटी स्क्रिप्ट के साथ पथ डालें। 4. 'Docs issue:' विषय टैग द्वारा आने वाले मेल को रूट करें ताकि रिपोर्ट एक ही स्थान पर आएं। 5. लूप बंद करें: जब आप किसी रिपोर्ट किए गए पेज को ठीक करते हैं, तो पाठक को एक लाइन का जवाब बग रिपोर्ट को सद्भावना में बदल देता है。 ## यह क्या बचाता है पहली बचत है **समस्याओं का पता लगाने में मेंटेनर का समय**। जब हर रिपोर्ट में पेज का नाम होता है, तो आप जासूसी के काम को छोड़कर सीधे समाधान पर जाते हैं। एक रिपोर्ट जो पहले बिना काम की 'कहीं कुछ गलत है' होती थी, वह दो मिनट का एडिट बन जाती है。 दूसरी बचत है **कम फंसे हुए यूज़र्स**। डॉक्यूमेंटेशन की गलतियां बढ़ती हैं: एक गलत इंस्टॉलेशन स्टेप सिर्फ एक बार फेल नहीं होता, बल्कि जब तक कोई उसे ठीक नहीं करता, तब तक हर नए आने वाले के लिए फेल होता है। 'एक पाठक ध्यान देता है' से 'एक मेंटेनर को ठीक से पता है कि कहां' तक का समय कम करने का मतलब है कि हर खराब हिस्सा बहुत कम लोगों को दूर करता है। किसी टूल के लिए जो अपनाने से बढ़ता है, नए लोगों के रास्ते की रुकावट हटाना ही विकास है。 तीसरी चीज़ है **फीडबैक की मात्रा और ईमानदारी**। क्योंकि रिपोर्ट करने में एक क्लिक लगता है और किसी अकाउंट की ज़रूरत नहीं होती, ज़्यादा पाठक ऐसा करते हैं — जिनमें वे लोग भी शामिल हैं जो कभी ट्रैकर इश्यू नहीं खोलते। आपको उन छोटी, शर्मनाक गलतियों के बारे में पता चलता है जो विश्वास को कम करती हैं, और आपको उनके बारे में तब पता चलता है जब वे अभी भी मायने रखती हैं。 ## इसे और भी बेहतर बनाएं - पथ के साथ **doc वर्ज़न या कमिट** को अपने आप भरें, ताकि आप बता सकें कि कोई रिपोर्ट हाल ही में किए गए बदलाव से पुरानी है या नहीं। - अपने docs में **404 पेजों** पर लिंक जोड़ें, जहां गायब पेज खुद ही एक उपयोगी संकेत है। - पते को **छिपा कर (obfuscated)** रखें ताकि बॉट्स इसे हज़ारों सार्वजनिक पेजों से चुरा न लें। - डिफ़ॉल्ट मेल ऐप के बिना वाले पाठकों के लिए एक दृश्यमान विकल्प प्रदान करें, जैसे कि एक सादा पता या एक ट्रैकर लिंक。 ## मुख्य बातें - बिना लोकेशन के Docs फीडबैक सिर्फ शोर है; पाठक शायद ही कभी इसे जोड़ने का काम करते हैं。 - हर पेज का "Report an issue" `mailto:` लिंक सटीक पथ को पहले से भर देता है, ताकि हर रिपोर्ट पर कार्रवाई की जा सके。 - ऑन-पेज ईमेल उन साधारण सुधारों को कैप्चर करता है जिन्हें एक ट्रैकर बाहर कर देता है, और फिर वास्तविक सुधारों के लिए ट्रैकर को फीड करता है。 - यह मेंटेनर का समय बचाता है, नए लोगों की रुकावटों को तेज़ी से दूर करता है, और उन छोटी गलतियों को सामने लाता है जो चुपचाप विश्वास को नुकसान पहुंचाती हैं。 आप [जनरेटर](/#generator) में अपना खुद का docs-फीडबैक लिंक बना सकते हैं, या नीचे दिए गए सेटअप को कॉपी कर सकते हैं।