क्या डॉक्यूमेंटेशन में बाहरी लिंक जोड़ना बुरा है?

Question

अक्सर मैं स्टैक ओवरफ्लो पर जवाब ढूंढकर खुद को कीड़े को हल करता हूं। क्या यह गलत है कि मैंने जो किया, उसका एक स्निपेट जोड़ना और फिर वेब से एक लेख या पृष्ठ पर एक लिंक जोड़ना?

Comments

संभावित डुप्लिकेट क्या मुझे स्रोत कोड में MSDN नोट या ढेर अतिप्रवाह लिंक जोड़ना चाहिए?

— gnat

FWIW मैं इसे हर समय करता हूं, और यहां तक कि यह भी पूछा गया कि StackExchange पर यह कैसे ठीक से किया जाए । ऐसा नहीं है कि यह आपके प्रश्न का उत्तर देता है, लेकिन इसके खिलाफ कुछ तर्क दिए जा सकते हैं।

के संभावित डुप्लिकेट क्या यह ठीक है एक प्रोग्राम की टिप्पणियों में क्यू एंड ए साइटों का एक लिंक डाल करने के लिए?

— डॉक्टर ब्राउन 14

क्या केवल लिंक (मेरे लिए ठीक है) के बारे में सवाल है, क्योंकि आप कोड / उत्तर के कुछ हिस्सों का भी उल्लेख करते हैं। यह कुछ ऐसा है जो मैं केवल एक जटिल एल्गोरिथ्म या प्रसंस्करण की व्याख्या करने के लिए करूंगा। जहां आप किसी समाधान के बारे में पढ़ते हैं वहां कोड संरचना और नामकरण स्पष्ट स्वतंत्र होना चाहिए।

— शाम 17:56 पर कुवेबल

Answer 1

मुझे नहीं लगता कि इसका बुरा, लेकिन बाहरी लिंक एक समाधान के जीवन चक्र से दूर जाने की बुरी आदत है। ऐसा करते समय, मैं एक पर्याप्त सारांश लगाने की सलाह देता हूं जो पाठक की मदद करेगा यदि लिंक अधिक कार्यात्मक नहीं है।

Comments

दो कारणों से एक सारांश को जोड़ना: 1) जैसा कि जिम ने बताया, यह पाठक को यह समझने में मदद करता है कि लिंक पुराना है या नहीं, और 2) यह डेवलपर को लिंक से कोड को कॉपी करने के लिए मजबूर करता है, ताकि वे समझ सकें कि वे क्या कॉपी कर रहे हैं। यह सुनिश्चित करने में मदद करता है कि कोड का उपयोग केवल इसलिए नहीं किया जा रहा है क्योंकि "यह समस्या को ठीक करता है"।

— मेजी एक्सई

Answer 2

यही कारण है कि कंपनियों का अपना ज्ञान भंडार होना चाहिए। उदाहरण के लिए, मेरी कंपनी के पास एक कॉरपोरेटिव रेडमाइन है, जिसका इस्तेमाल प्रोजेक्ट के प्रबंधन, टिकटिंग (बग्स और टास्क ट्रैकिंग) के लिए किया जाता है और जिस उपकरण का मैं सबसे अधिक उपयोग करता हूं, वह है विकी । ये सभी सुविधाएँ प्रति प्रोजेक्ट :-)

प्रोजेक्ट की विकी पर हमारे पास क्या है?

• प्रलेखन के लिए लिंक: कार्यात्मक, तकनीकी, वास्तुकला, आवश्यकताएं।
• अभिनेता शामिल: परियोजना प्रबंधक, देवता, ग्राहक के प्रमुख खाता प्रबंधक, ...
• प्रति वातावरण विवरण: वर्चुअल मशीन, OS, सर्वर, कॉन्फ़िगरेशन ...
• विविध: परियोजना के जीवनकाल के दौरान सीखी गई कोई भी महत्वपूर्ण / रोचक बात (परियोजना से संबंधित)।
• कुछ और पेज

मैं Misc विकि पर ग्रंथ सूची (लिंक) डालता हूं । लेकिन केवल उन लोगों से जिन पर मुझे भरोसा है:

• स्टैक ओवरफ्लो : सकारात्मक वोट और अच्छी तरह से तर्क दिया
• सॉफ्टवेयर इंजीनियरिंग स्टैकएक्सचेंज : सकारात्मक वोट और अच्छी तरह से तर्क दिया
• MKyong.com : मुझे यह पेज पसंद है। यह वास्तव में उपयोगी है और इसके ट्यूटोरियल वास्तव में आसान हैं
• MDN
• W3C.org
• W3Schools : इसका प्रलेखन इंटरैक्टिव (अधिकांश मामलों में) और उपयोगकर्ता के अनुकूल है।
• OWASP : सुरक्षा और कमजोरियों से संबंधित मुद्दों को संदर्भित करने के लिए
• आधिकारिक वेब पेज: कभी-कभी सबसे अच्छा ट्यूटोरियल या स्पष्टीकरण आधिकारिक वेब पेज पर होते हैं।

मेरी ग्रंथ सूची मेरे द्वारा टाइप किए गए सारांश के साथ आती है, ताकि यह सुनिश्चित हो सके कि मैं समझ गया हूं कि मैं क्या लिंक कर रहा हूं। मैं जवादोक को यथासंभव स्पष्ट रखने की कोशिश करता हूं। कोड में प्रत्येक लिंक Redmine की विकी या Redmine के इश्यू कोड को संदर्भित कर रहा है।

Redmine जैसे उपकरणों की अनुपस्थिति में, मुझे इन उद्देश्यों के लिए उपयोगी मार्कडाउन फाइलें मिलीं । इन फ़ाइलों के कारण डेवलपर्स के लिए कुल मिलाकर SCM में हैं और कोड के साथ आता है।

Comments

मैं W3Schools.com पर भरोसा करने के अलावा सब कुछ से सहमत हूं। आप एमडीएन पर सबसे अधिक पा सकते हैं, जिस पर अधिक अधिकार है।

— अल्टरनेटेक्स

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

— Laiv

Answer 3

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

उदाहरण के लिए, जब आप विकिपीडिया से लिंक करते हैं, तो आपको जेनेरिक लेख के नाम के बजाय आज के संस्करण से स्पष्ट रूप से लिंक करना चाहिए। Stackexchange.com के लिए, ठीक है, इस समय यह दूर जाने की संभावना नहीं दिखती है, लेकिन सवालों को संपादित किया जाता है या यहां तक ​​कि हर समय हटा दिया जाता है, और पांच साल के समय में एक नया नया एकत्रित बिंदु साथ आ सकता है। मैं ऐसे लटकने वाले दस्तावेज़ों को जोखिम में नहीं डालूँगा जो आपके संगठन के लिए बाहरी रूप से एक साइट पर पर्याप्त व्यावसायिक मूल्य वहन करते हैं।

Comments

"वेबैक मशीन - इंटरनेट आर्काइव" (web.archive.org/) हटाए गए सामग्री की जांच करने के लिए एक अच्छी जगह है।

— क्रॉस्टर