त्रुटि संदेश में प्रासंगिक प्रलेखन के लिए एक लिंक शामिल करें?


10

हम एक वाणिज्यिक पुस्तकालय और कोड उदाहरण बनाते हैं जो बाहरी डेवलपर्स द्वारा उपयोग किए जा रहे हैं। हमारे पास (पंजीकृत उपयोगकर्ताओं के लिए उपलब्ध है) प्रलेखन, जो बड़े पैमाने पर पुस्तकालय का उपयोग करने के बारे में बताता है।

कई डेवलपर्स पहली बार उपयोगकर्ता हैं, इसलिए बहुत अधिक अल्पविकसित त्रुटियां सामने आई हैं।

क्या त्रुटि लॉग में प्रलेखन के लिंक शामिल करना उचित है? संभावित डाउनसाइड क्या हैं? मैं कुछ पूर्वाभास कर सकता हूं, लेकिन निम्नलिखित पर काबू पाना संभव है

  • डॉक्यूमेंटेशन URL आउट ऑफ़ डेट
  • संस्करण विशिष्ट त्रुटियां जो नवीनतम प्रलेखन में परिलक्षित नहीं होती हैं
  • कुछ और गलत है, और हम उसे अप्रासंगिक दस्तावेज भेजकर डेवलपर के समय को बर्बाद कर रहे हैं

मेरे कहने का एक उदाहरण के नीचे, क्या बोल्ड टेक्स्ट को जोड़ना एक अच्छा विचार है?

[त्रुटि] लक्ष्य को निष्पादित करने में विफल हुआ। org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: प्रोजेक्ट स्टैंडअलोन-पोम पर जनरेट (डिफ़ॉल्ट-क्ली): वांछित ऑर्किटेक्चर मौजूद नहीं है (com.example.library)। archetypes: पुस्तकालय- archetype-blank: 1.2.3.0) -> कृपया अधिक जानकारी और संभावित समस्या निवारण के लिए http://example.com/docs/setting-up-an-archetype देखें


5
इमो, वर्णनात्मक त्रुटियां अच्छी हैं, और जो पेशकश करते हैं वे और भी बेहतर मदद करते हैं।
सेस टिम्मरमैन

@CeesTimmerman मैं पूरी तरह से सहमत हूं, लेकिन मुझे इस प्रकार के संदेशों का सामना नहीं करना पड़ा है। यह मुझे ऐसा करने में संकोच करने लगता है, क्योंकि शायद इसका एक अच्छा कारण है ..
वॉन लॉयन

मैंने उन्हें 404 पृष्ठों पर देखा है और सॉफ्टवेयर में मुझे याद नहीं है, हो सकता है कि Homebrew।
सेस टिम्मरमैन

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

3
@VonLion: चीजों को सिर्फ इसलिए करना क्योंकि हर कोई उन्हें कर रहा है, औसत दर्जे का नुस्खा है।
रॉबर्ट हार्वे

जवाबों:


8

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

अंत में, आप शायद पहले से ही नीलसन के कंप्यूटर प्रलेखन के पहले कानून को जानते हैं: लोग इसे नहीं पढ़ते हैं। यह खोज वेबसाइटों के लिए और भी मजबूत है, जहाँ उपयोगकर्ता वास्तव में किसी भी पढ़ने से कतराते हैं जो उनके कार्य के लिए आवश्यक नहीं है। मदद पर क्लिक करें? कभी नहीँ।

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

हाइपरटेक्स्ट लिंक का उपयोग पृष्ठ पर एक संक्षिप्त त्रुटि संदेश को अतिरिक्त पृष्ठभूमि सामग्री या समस्या के स्पष्टीकरण के साथ जोड़ने के लिए किया जा सकता है। (हालांकि, इसे ज़्यादा मत करो।)


इसके लिए शुक्रिया! यह थोड़ा पुराना है, हालांकि 2001 से पहले हम इस पूरी 'वेब' चीज़ को सचमुच समझ रहे थे :-)
वॉन लॉयन

3
यह अभी भी अच्छी सलाह है, लेकिन शायद जॉन कार्मैक का यह हालिया ट्वीट मदद करता है।
सेस टिम्मरमैन

6

हाँ सबसे निश्चित रूप से लेकिन

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

यदि आप जावा या .NET के साथ विकसित होते हैं, तो डॉक्टर को एक जार फ़ाइल या DLL फ़ाइल में शामिल किया जा सकता है और उपसर्ग को बदलकर आपका कोड इसके बजाय स्थानीय रूप से प्राप्त कर सकता है।

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

मेरे द्वारा बनाए गए कुछ सबसे सफल टूल ने एक समान दृष्टिकोण लिया है जहां त्रुटि संदेश वास्तविक उपयोगकर्ता को लक्षित किया गया था जो कि संभवतः कार्य को निष्पादित करेगा। इसका मतलब यह था कि मुझे अपवाद का एक बहुत कुछ करना था और यह सुनिश्चित करने के लिए लपेटना था कि त्रुटि अमूर्त के उपयुक्त स्तर पर है। मैंने यह भी सुनिश्चित किया कि प्रत्येक त्रुटि संदेश में संभावित समाधानों में त्रुटियों और बिंदुओं के सबसे संभावित स्रोतों को शामिल किया जाएगा "क्या आप कॉन्फिडेंस कॉन्फिडेंस वैल्यू सेट करना भूल गए?", "सुनिश्चित करें कि xxx और yy उन्हें अलग-अलग नाम देकर संघर्ष न करें" आदि। जहां XXX और whatnot उस संदर्भ से उत्पन्न होगा जहां त्रुटि हुई।

यह दृष्टिकोण कुछ हद तक सरल था लेकिन अधिक सीमित था। यह हालांकि पक्ष था कि प्रलेखन हमेशा मौजूद होगा जब कोई लिंक संभव सड़ांध की आवश्यकता होती है।

आपका दृष्टिकोण अगला विकास है। बहुत अधिक जटिल है, लेकिन अधिक संभावित रिटर्न भी है। यह महंगा होगा, लेकिन अगर सही किया जाता है तो आसानी से खुद के लिए भुगतान करना होगा।


इस व्यापक उत्तर के लिए धन्यवाद! लिंक रोट निश्चित रूप से एक समस्या होगी, लेकिन उम्मीद है कि 404-निगरानी पर सतर्क रहना पर्याप्त होगा; यह निश्चित रूप से देव टीम से बहुत प्रतिबद्धता और प्रयास लेगा (यह एक मौजूदा कोडबेस है ... यदि यह नया है तो इसे शुरू करना आसान होगा), लेकिन जैसा कि आप कहते हैं, लाभ इसके लायक हो सकता है!
वॉन लॉयन


5

आपको ऑनलाइन के बजाय लाइब्रेरी के साथ बंडल किए गए ऑफ़लाइन दस्तावेज़ों की ओर इशारा करना चाहिए।

(com.example.library.archetypes: Library-archetype-blank: 1.2.3.0) -> कृपया अधिक जानकारी और संभावित समस्या निवारण के लिए /usr/share/myprog-3.8.1/docs/setting-up-an-arthhetype देखें।

(जाहिर है अगर यह एक विंडोज लाइब्रेरी है, तो रास्ता अलग होगा)।

यहाँ लाभ हैं:

  • इस तरह से प्रलेखन हमेशा पुस्तकालय के साथ सिंक में होता है। लोग पुराने पुस्तकालय संस्करणों के साथ विकसित होते हैं और उनका निवारण करते हैं। और आपकी कंपनी अपना नाम बदल सकती है, उत्पाद का नाम बदल सकती है, या कोई व्यक्ति नवीनीकरण पर गेंद को गिरा सकता है example.com

  • वेब तेजी से बदलता है। आपके द्वारा दिया गया लिंक है http, लेकिन कुछ वर्षों में इसके संभावित प्रमुख ब्राउज़र केवल समर्थन करेंगे https। या हम सब वापस आ सकते हैंgopher प्रोटोकॉल में हैं।

  • एप्लिकेशन समस्या निवारण हमेशा इंटरनेट एक्सेस (या आपके डोमेन तक कम से कम प्रत्यक्ष पहुंच) वाले वातावरण में नहीं होता है।

  • आप अपने प्रलेखन का उल्लेख "प्रमाणीकरण" दीवार के पीछे है। किसी त्रुटि संदेश को समझने के लिए सिर्फ एक वेबसाइट पर एक खाता बनाने के बाद सुखद नहीं है (यही कारण है कि SO को लोगों को लॉगिन करने की आवश्यकता नहीं है)।


3

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

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

हां, मैं इनकी खोज कर सकूंगा। यकीन है, मुझे पता है कि यह हुआ क्योंकि कुछ अशक्त छोड़ दिया गया था और फिर इस्तेमाल किया। क्या हमेशा स्पष्ट नहीं है, हालांकि क्यों कुछ अशक्त छोड़ दिया गया था।

तो यकीन है, इन सभी अन्य प्रलेखन समाधान पर विचार करें। लेकिन सबसे बड़ी चीज जो आप कर सकते हैं, वह मुझे सबसे अच्छा कर देगा बस मुझे कुछ दे सकता है जो मैं कर सकता हूं।

मान जाओ ना?


आप फ़ाइल और लाइन नंबर के लिए खोज करने की कोशिश कर सकते हैं searchcode.com
सीस टिमरमैन
हमारी साइट का प्रयोग करके, आप स्वीकार करते हैं कि आपने हमारी Cookie Policy और निजता नीति को पढ़ और समझा लिया है।
Licensed under cc by-sa 3.0 with attribution required.