บทช่วยสอนของนักพัฒนาทำให้ผู้เริ่มต้นหลงทางด้วยศัพท์เทคนิคและขั้นตอนที่ขาดหาย

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

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

ปัญหาทั่วไปที่พบในบทช่วยสอนการเขียนโปรแกรม:

• ศัพท์เทคนิคและตัวย่อที่ไม่มีคำอธิบาย
• ขาดขั้นตอนการติดตั้งหรือการตั้งค่า
• คาดเดาเกี่ยวกับสภาพแวดล้อมการพัฒนาของผู้ใช้
• ข้ามขั้นตอนกลางที่ "เห็นได้ชัด"
• ขาดตัวอย่างโค้ดที่ใช้งานได้จริง
• คำอธิบายที่ยาวเกินไปจนทำให้ผู้อ่านเสียสมาธิ
• คำแนะนำที่ล้าสมัยหลังจากซอฟต์แวร์อัปเดต

ปัญหาคำสาปแห่งความรู้

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

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

บทความวิชาการ เทียบกับ คู่มือสำหรับผู้เริ่มต้น

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

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

ขั้นตอนที่ขาดหายและสมมติฐานเกี่ยวกับสภาพแวดล้อม

ธีมที่เกิดขึ้นซ้ำๆ ในการอภิปรายมุ่งเน้นไปที่บทช่วยสอนที่ข้ามขั้นตอนสำคัญหรือสมมติสภาพแวดล้อมการพัฒนาเฉพาะ นักเขียนมักจะลืมกล่าวถึงข้อกำหนดพื้นฐานที่ดูเหมือนจะเป็นเรื่องธรรมดา เช่น การติดตั้ง compiler การตั้งค่าเครื่องมือพัฒนา หรือการอธิบายการดำเนินการ command-line ที่กลายเป็นธรรมชาติสำหรับพวกเขาแล้ว

หากฉันต้องหยุดเพื่ออธิบายว่า cat หรือ sudo หรือ | หมายถึงอะไรในทุกเอกสารที่ฉันเขียน ฉันจะไม่มีเวลาทำอะไรให้เสร็จเลย

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

ตัวอย่างโค้ดในฐานะเอกสาร

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

แนวทางนี้สะท้อนวิธีที่บริษัทเทคโนโลยีใหญ่ๆ จัดโครงสร้างเอกสารของพวกเขา โดยให้ตัวอย่างโค้ดหลายรายการในภาษาการเขียนโปรแกรมต่างๆ เพื่อแสดงแนวคิดอย่างชัดเจน

หprinciples การเขียนเอกสารที่มีประสิทธิภาพ:

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

ปัญหาการปรับระดับความยาก

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

อย่างไรก็ตาม แนวทางนี้สามารถสร้างอุปสรรคสำหรับผู้เรียนที่มีแรงจูงใจซึ่งต้องการคำแนะนำที่ดีกว่ามากกว่าความรู้พื้นฐานเพิ่มเติม

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

อ้างอิง: How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner