การเพิ่มลิงก์ภายนอกในเอกสารประกอบเป็นเรื่องที่ผิดหรือไม่?

9

บ่อยครั้งที่ฉันพบว่าตัวเองกำลังแก้ไขข้อบกพร่องด้วยการหาคำตอบใน Stack Overflow มันเป็นการปฏิบัติที่ไม่ถูกต้องหรือไม่ที่จะเพิ่มตัวอย่างของสาเหตุที่ฉันทำในสิ่งที่ฉันทำและเพิ่มลิงค์ไปยังบทความหรือหน้าเว็บจากเว็บ

documentation

— TruthOf42
แหล่งที่มา

การทำซ้ำที่เป็นไปได้ของฉันควรเพิ่มบันทึก MSDN หรือการเชื่อมโยงสแต็คโอเวอร์โฟลว์ในซอร์สโค้ดหรือไม่

— ริ้น

FWIW ฉันทำมันตลอดเวลาและแม้กระทั่งถามว่าการทำเช่นนี้อย่างถูกต้องบน StackExchange ไม่ใช่ว่ามันตอบคำถามของคุณ แต่มีข้อโต้แย้งบางอย่างสำหรับและต่อต้านสามารถพบได้ที่นั่น

4

มีความเป็นไปได้ที่ซ้ำกันของมันตกลงที่จะนำลิงค์ไปยังเว็บไซต์ถาม - ตอบในความคิดเห็นของโปรแกรมหรือไม่?

— Doc Brown

เป็นคำถามเฉพาะเกี่ยวกับลิงค์ (OK สำหรับฉัน) เพราะคุณยังพูดถึงการคัดลอกส่วนของรหัส / คำตอบ นี่คือสิ่งที่ฉันจะทำเพื่ออธิบายอัลกอริทึมที่ซับซ้อนหรือการประมวลผล โครงสร้างรหัสและการตั้งชื่อควรมีความชัดเจนโดยไม่ขึ้นกับที่คุณอ่านเกี่ยวกับโซลูชัน

— Kwebble

14

ฉันไม่คิดว่ามันเลวร้าย แต่การเชื่อมโยงภายนอกมีนิสัยที่ไม่ดีที่จะออกไปตลอดวงจรชีวิตของการแก้ปัญหา เมื่อทำเช่นนั้นฉันขอแนะนำให้วางบทสรุปที่เพียงพอซึ่งจะช่วยให้ผู้อ่านทราบว่าลิงก์นั้นใช้งานไม่ได้อีกต่อไป

— จิมรัช
แหล่งที่มา

3

การเพิ่มข้อมูลสรุปมีประโยชน์ด้วยเหตุผลสองประการ: 1) ตามที่จิมชี้ให้เห็นจะช่วยให้ผู้อ่านเข้าใจว่าลิงก์นั้นล้าสมัยหรือไม่และ 2) บังคับให้นักพัฒนาคัดลอกโค้ดจากลิงก์เพื่อทำความเข้าใจกับสิ่งที่พวกเขากำลังคัดลอก วิธีนี้ช่วยให้แน่ใจได้ว่ารหัสไม่ได้ถูกใช้เพียงเพราะ "ช่วยแก้ปัญหา"

— Mage Xy

7

นี่คือเหตุผลที่ บริษัท ควรมีคลังความรู้ของตัวเอง ยกตัวอย่างเช่น บริษัท ของฉันมี corporative Redmineซึ่งจะใช้สำหรับผู้บริหารโครงการบัตรโดยสาร (ข้อบกพร่องและงานติดตาม) และเครื่องมือที่ผมใช้ส่วนใหญ่วิกิพีเดีย คุณสมบัติทั้งหมดต่อโครงการ :-)

เรามีอะไรในวิกิของโครงการ

ลิงค์ไปยังเอกสาร: หน้าที่, เทคนิค, สถาปัตยกรรม, ข้อกำหนด
นักแสดงที่เกี่ยวข้อง: ผู้จัดการโครงการ Devs ผู้จัดการบัญชีหลักของลูกค้า ...
คำอธิบายต่อสภาพแวดล้อม: เครื่องเสมือน, ระบบปฏิบัติการ, เซิร์ฟเวอร์, การกำหนดค่า ...
อื่น ๆ : สิ่งสำคัญ / น่าสนใจใด ๆ (เกี่ยวข้องกับโครงการ) ที่ได้เรียนรู้ในช่วงชีวิตของโครงการ
บางหน้ามากขึ้น

ฉันใส่บรรณานุกรม (ลิงก์) ที่Misc wiki แต่จากคนที่ฉันไว้วางใจเท่านั้น:

กองมากเกินไป : คะแนนโหวตเป็นบวกและเป็นที่ถกเถียงกันดี
Stackexchange วิศวกรรมซอฟต์แวร์ : คะแนนโหวตเป็นบวกและเป็นที่ถกเถียงกันอยู่
MKyong.com : ฉันชอบหน้านี้ มันมีประโยชน์จริงๆและแบบฝึกหัดนั้นง่ายต่อการติดตาม
MDN
W3C.org
W3Schools : เอกสารมันเป็นแบบโต้ตอบ (ส่วนใหญ่กรณี) และใช้งานง่าย
OWASP : สำหรับปัญหาการอ้างอิงที่เกี่ยวข้องกับความปลอดภัยและช่องโหว่
หน้าเว็บทางการ: บางครั้งบทเรียนหรือคำอธิบายที่ดีที่สุดอยู่ที่หน้าเว็บทางการ

บรรณานุกรมของฉันมาพร้อมกับบทสรุปที่พิมพ์ลงโดยฉันเพื่อให้แน่ใจว่าฉันเข้าใจสิ่งที่ฉันกำลังเชื่อมโยง ฉันพยายามทำให้ Javadoc ชัดเจนที่สุด ทุกลิงก์ในรหัสอ้างอิงถึงวิกิของ Redmine หรือรหัสปัญหาของ Redmine

ในกรณีที่ไม่มีเครื่องมือเช่น Redmine ฉันพบว่าเป็นไฟล์Markdownที่มีประโยชน์และมีประโยชน์สำหรับวัตถุประสงค์เหล่านี้ โดยรวมสำหรับนักพัฒนาเนื่องจากไฟล์เหล่านี้อยู่ใน SCM และมาพร้อมกับรหัส

— LAIV
แหล่งที่มา

1

ฉันเห็นด้วยกับทุกอย่างยกเว้นที่ไว้วางใจ W3Schools.com คุณสามารถค้นหาสิ่งที่มีอยู่ใน MDN ซึ่งมีสิทธิอำนาจมากกว่า

— Alternatex

1

W3schools มีความยาวมากกว่า MDN ฉันอาจจะผิด แต่ฉันคิดว่า W3schools มีเนื้อหาเพิ่มเติมแบบฝึกหัดและเอกสารเทคโนโลยีเว็บ แม้จะมีปัญหามันก็ยังคงเป็นหนึ่งในการอ้างอิงที่ดีที่สุดสำหรับผู้เริ่มต้นเพราะเนื้อหาเป็นวิธีที่ใช้งานง่ายและโต้ตอบ ในด้านบวก MDN มีชุมชนที่ยอดเยี่ยมที่สนับสนุนเนื้อหา แต่ในทางกลับกันมันไม่เคยเป็นกลางในเอกสารประกอบเพราะมีเบราว์เซอร์ที่จะปกป้อง อย่างไรก็ตามฉันเห็นด้วยกับคุณตอนนี้วัน MDN ดูเหมือนจะมีอำนาจมากขึ้น หากคุณไม่รังเกียจฉันจะเพิ่มการอ้างอิงไปยังคำตอบของฉัน

— Laiv

4

ลิงก์ไปยังเว็บนั้นค่อนข้างมีปัญหาเป็นเอกสารเพราะอินเทอร์เน็ตไม่รับประกันว่าเนื้อหาที่คุณเห็นอยู่นั้นจะเหมือนกันกับที่ผู้อ่านเอกสารในอนาคตจะเห็น ถ้าเป็นไปได้พยายามเชื่อมโยงกับแหล่งข้อมูลที่ไม่น่าจะเปลี่ยนแปลงได้

ตัวอย่างเช่นเมื่อคุณเชื่อมโยงไปยัง Wikipedia คุณควรเชื่อมโยงไปยังรุ่นของวันนี้อย่างชัดเจนมากกว่าชื่อบทความทั่วไป สำหรับ stackexchange.com ตอนนี้ดูเหมือนว่าไม่น่าจะหายไป แต่คำถามจะได้รับการแก้ไขหรือลบออกตลอดเวลาและในเวลาห้าปีที่ผ่านมาอาจมีจุดรวมตัวใหม่ที่น่าสนใจ ฉันจะไม่เสี่ยงกับเอกสารที่ห้อยอยู่ซึ่งมีมูลค่าทางธุรกิจที่สำคัญบนไซต์ที่อยู่นอกองค์กรของคุณ

— Kilian Foth
แหล่งที่มา

"Wayback Machine - Internet Archive" (web.archive.org/) เป็นสถานที่ที่ดีในการตรวจสอบเนื้อหาที่ถูกลบ

— Kromster