ในฐานะนักพัฒนามือใหม่ ฉันอ่านบทช่วยสอนที่คุณ (นักพัฒนา) เขียนให้ฉันอย่างไร

 (anniemueller.com)
5 คะแนน โดย GN⁺ 2025-09-23 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • บทความที่ถ่ายทอด ความสับสนและอุปสรรคเวลามือใหม่อ่านบทช่วยสอนทางเทคนิค ที่นักพัฒนาเขียนไว้ด้วยอารมณ์ขัน
  • คำศัพท์เฉพาะและตัวย่อ ที่นักพัฒนามักใช้ ฟังดูสำหรับมือใหม่เหมือน ‘ภาษาต่างดาว’ ที่ไม่มีบริบทใด ๆ เลย
  • ขั้นตอนการติดตั้ง, พาธไฟล์, คำสั่งเทอร์มินัล ในบทช่วยสอนมักซับซ้อนเกินไปหรือถูกข้ามรายละเอียด จนทำความเข้าใจได้ยาก
  • ผู้เขียนชี้ว่า คำอธิบายที่ดูเป็นเรื่องธรรมดาในมุมมองของนักพัฒนา อาจกลายเป็นอุปสรรคที่ทำให้มือใหม่ต้อง ค้นหาหลายชั่วโมงและลองผิดลองถูก
  • บทความนี้เตือนนักพัฒนาที่เขียนบทช่วยสอนว่า ควรอธิบายให้เป็นมิตรและชัดเจนขึ้นจากมุมมองของผู้เริ่มต้น

ที่มาของบทความและประเด็นปัญหา

  • ผู้เขียนเล่าประสบการณ์ในฐานะมือใหม่ที่ไม่ใช่นักพัฒนา ขณะอ่านบทช่วยสอนที่นักพัฒนาเป็นคนเขียน
  • มีการเสียดสีสถานการณ์ที่ คำศัพท์ทางเทคนิคและชื่อเครื่องมือ ในบทช่วยสอนไม่ทำให้เข้าใจได้เลยว่าหมายถึงอะไร
  • ตัวอย่างเช่น ใช้ ชื่อเทคนิคสมมติ อย่าง Hoobijag, Snarfus, Shamrock portal เพื่อเน้นว่าจากสายตามือใหม่ ทุกอย่างดูซับซ้อนไปหมด

แปลต้นฉบับ

“สวัสดี! ฉันเป็นนักพัฒนา ประสบการณ์ที่เกี่ยวข้องของฉันมีดังนี้: ฉันเขียนโค้ดด้วย Hoobijag และบางครั้งก็ใช้ jabbernocks ด้วย แล้วก็แน่นอนว่าฉันทำ ABCDE++++ ด้วย (แต่ไม่มีทางเป็น ABCDE+/^+ เด็ดขาด นั่นมันไร้สาระใช่ไหม? ฮ่าๆ!) และฉันชอบทำงานกับ Shoobababoo บางครั้งก็จัดการ kleptomitrons ด้วย ฉันได้ไปทำโค้ดเกี่ยวกับ Shoobaboo ที่ Company[1] แล้วนั่นก็พาฉันมาสู่ Snarfus เอาล่ะ มาเริ่มกันเลย!

เกี่ยวกับบทช่วยสอนนี้

ตอนแรกฉันเริ่มทำอะไรที่ง่ายมาก[2] ด้วย Snarfus แต่ยิ่งใช้ก็ยิ่งเห็นศักยภาพของมัน! chromus อาจจะพันกันนิดหน่อย แต่จริง ๆ แล้วมันใช้งานได้อเนกประสงค์มาก ดังนั้นฉันเลยเริ่ม argyling pintafore ด้วย quagmire แทน hoobastank! บ้าดีใช่ไหม ฉันรู้ แต่ก็พอใช้ได้ระดับหนึ่ง และจริง ๆ แล้วก็ค่อนข้างสนุก… จนกระทั่งเจออุปสรรคใหญ่: fisterfunk ไม่ยอมคุยกับ shamrock portal เลย แถมยังไม่ส่ง beep-boops ไปที่ Snarfus ด้วย! แน่นอนว่าคุณรู้ว่านั่นหมายความว่าอะไร[3]— ตอนนี้ทั้ง hoob-อุโมงค์ถูก gramelions อุดตันหมดแล้ว ยอมรับไม่ได้เลย

ฉันเกือบจะยอมแพ้อยู่แล้ว แต่แล้วฉันก็นึกออกว่า: ถ้าเชื่อม backside Snarfus stagnator เข้ากับ backside shamrock Klingon troglodyte emulater ก็ใช้ได้! ทุกอย่างเริ่ม beep-boops กับ ding-dongs แล้วในที่สุดก็เข้าสู่หัวข้อจริงของบทช่วยสอนนี้เสียที และฉันก็สามารถทำสิ่งง่าย ๆ ได้ในแบบที่ต้องการ! เจ๋งดีใช่ไหม[4]

ดังนั้นวิธีตั้งค่าก็คือ:

  1. ในเทอร์มินัล พิมพ์ ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas
  2. ตอนนี้ไปที่ folder/hidden/deep/in/the/file/system/surprise!.file แล้วคัดลอกเนื้อหาไฟล์ ถ้ามันไม่ได้อยู่ตรงนั้น มันอาจจะอยู่ที่ library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file
  3. กลับไปที่เทอร์มินัลอีกครั้ง วางเนื้อหาไฟล์ แล้วพิมพ์ 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!
  4. Boop![5]
  5. เปิด Snarfus แล้วอัปโหลดไฟล์ที่คุณเพิ่งสร้าง
  6. เพื่อความสนุก ถ้าคุณอยาก unsham chronostatiomatrix ก็สามารถรัน —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] ได้ด้วย เป็นทางเลือก
  7. เสร็จ!

บอกฉันด้วยว่าเป็นอย่างไรบ้าง ฉันก็อยากรู้เหมือนกันว่ามีใครใช้วิธีนี้กับ GewGawGamma หรือ ometer2.7 ไหม”

คำอธิบายเชิงอรรถ

  1. ดูเหมือนจะเป็นบริษัทดัง แต่ฉันไม่รู้จัก
  2. ไม่ได้ง่ายเลยสักนิด
  3. ไม่รู้ว่าหมายความว่าอะไร
  4. มันก็ดูเจ๋งดี แต่ฉันก็ยังไม่เข้าใจอยู่ดี อย่างน้อยก็ดีใจที่คุณทำได้
  5. สามขั้นตอนแรกน่าจะต้องใช้เวลาประมาณ 7 ชั่วโมงกับการค้นหา 193 ครั้ง แต่พอไปถึง Boop! ได้แล้วจะสะใจมาก

ปิดท้าย

  • “นี่เป็นแค่บทความเขียนเล่นสนุก ขอบคุณจากใจจริงถึงทุกคนที่แบ่งปันความรู้และเขียนบทช่วยสอนไว้”

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2025-09-23
ความคิดเห็นจาก Hacker News

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

    • มีประสบการณ์ว่าปัญหาแบบนี้เกิดบ่อยเวลาใช้เอกสารของ Apple คำจำกัดความในเอกสารมักวนอธิบายแค่ชื่อเดิมโดยไม่ให้คำอธิบายจริงๆ ควรเขียนให้เป็นรูปธรรมกว่านี้
    • กฎว่า "อย่าพูด แค่สังเกต" ดูเหมือนง่าย แต่ในความเป็นจริงหลายคนอดไม่ได้ที่จะอธิบายหรือให้คำใบ้ บางคนถึงขั้นจับเมาส์ทำให้เลย เพื่อหลีกเลี่ยงปฏิกิริยาแบบมนุษย์นี้ การมีผู้ดำเนินรายการที่เป็นกลางแยกต่างหาก แล้วให้ผู้เขียน/นักพัฒนาเป็นฝ่ายสังเกตอย่างเดียวก็ช่วยได้ แต่การฝึกทักษะ "แค่เฝ้าดู" นั้นสำคัญมาก และถ้าอยากพัฒนาไปอีก ขอแนะนำให้รู้จัก "think-aloud protocol(โปรโตคอลการพูดความคิดออกมา)"
    • เอกสาร onboarding ของหลายทีมในบริษัทส่วนใหญ่คุณภาพแย่มาก จนกลายเป็นหน้าต่างที่เผยให้เห็นภาระงานจริงล่วงหน้า สามทีมล่าสุดที่เข้าร่วมมา เอกสารแทบไม่มีหรือเก่ามาก จนต้องเดินหาคนที่เกี่ยวข้องเองเพื่อขอสิทธิ์เข้าถึงหรือข้อมูล pipeline การ deploy และระหว่างนั้นก็ต้องเขียนเอกสารใหม่ไปด้วย แต่พอมีระบบหรือสิทธิ์ใหม่เพิ่มเข้ามา เอกสารก็ล้าสมัยทันที วนเป็นวงจรไม่รู้จบ มีเพียงทีมเดียวที่ตั้งค่าสภาพแวดล้อมที่ต้องใช้ให้ครบภายในสองวัน และประสบการณ์นั้นยอดเยี่ยมที่สุด ตอนนี้กำลังพยายามปรับปรุงสภาพแวดล้อมด้านเอกสารทั้งระบบในทีม devex ใหม่
    • การ onboarding โดยต้องอ่านเอกสารการตั้งค่าที่ห่วยๆ นั้นให้ความรู้สึกเครียดขึ้นสิบเท่าจริงๆ มักสนับสนุนให้พนักงานใหม่แก้ไขปัญหาที่ตัวเองเจอเป็น contribution แรกทันที เพราะคนใหม่ยังไม่มีบริบทใดๆ จึงทำหน้าที่ reviewer ที่ดีที่สุดได้
    • องค์กรของเราก็ใช้ workflow แบบเดียวกัน ให้คนที่มีประสบการณ์น้อยทำตามเอกสาร แล้วหลังจากนั้นก็สนับสนุนให้ทุกคนช่วยกันปรับปรุงเอกสารอย่างต่อเนื่อง เพราะคนใหม่มักมองเห็น "จุดบอด" ที่คนทำมานานมองไม่เห็น จากประสบการณ์ ได้บทเรียนว่าการจัดการความมั่นใจของผู้ใช้ก็สำคัญมาก ดังนั้นเวลามีขั้นตอนอย่าง "ให้รันคำสั่งเชลล์นี้" จะพับบางส่วนไว้ให้โดยค่าเริ่มต้นเสมอ (เช่น ตัวอย่าง output ที่รันสำเร็จ, คำเตือนที่ละเลยได้, รายการ error ที่อาจเกิดขึ้นและวิธีจัดการ, คำอธิบายคำสั่งที่ซับซ้อน เป็นต้น) บางขั้นตอนมีคำอธิบายยาวเท่าหนึ่งหน้าเลย แต่ในช่วง onboarding รายละเอียดแบบนี้ช่วยได้มากจริงๆ

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

    • เผื่อไว้เป็นข้อมูล ชื่อที่ส่งไปเดิมคือ "คนที่ไม่ใช่นักพัฒนา" แต่ภายหลังถูกเปลี่ยนเป็น "นักพัฒนามือใหม่" ผู้เขียนเป็นบล็อกเกอร์ที่ไม่ใช่ผู้เชี่ยวชาญสายเทคนิค และกว่าจะจัดการเว็บไซต์หรือ CSS ได้ก็คงต้องอ้างอิงเอกสารเทคนิคหลายแหล่ง เดิมทีอาจเหมาะกว่าถ้าจะคุยเรื่องการเผยแพร่เว็บไซต์และการขาดเอกสารสำหรับคนทั่วไป แต่ก็ไม่เป็นไรถ้าชุมชน HN จะพาการสนทนาไปอีกทาง
    • การแยกความต่างนี้สำคัญมาก Annie ผู้เขียนบอกเองว่าทำงานด้าน "คอนเทนต์/เอกสาร" และมีงานอดิเรกเกี่ยวกับ CSS จึงอยู่ในกลุ่ม "นักพัฒนางานอดิเรกที่ไม่ใช่มืออาชีพ" ซึ่งน่าจะเป็นกลุ่มที่เติบโตขึ้นเรื่อยๆ เวลาจะเขียน tutorial ที่รวมทั้งมือใหม่และคนที่ไม่ใช่นักพัฒนา แค่เติมคำอธิบายสั้นๆ ให้ประโยคอย่าง cd ~/.snarfus(ถ้าไม่มีโฟลเดอร์ก็ให้สร้างขึ้นมา) ก็เพียงพอแล้ว ตอนสมัยติดตั้ง Debian เองก็เคยได้ประโยชน์มหาศาลจากคำอธิบายเล็กๆ แบบนี้
    • ตอนเริ่มเรียนเขียนโปรแกรม เว็บไซต์ที่ประทับใจมากคือ "FromZero" เพราะอธิบายตั้งแต่การติดตั้ง IDE ไปจนถึงการเปิดคอนโซลแบบทีละขั้น และถ้ามีศัพท์ที่ยังไม่คุ้นก็จะปลอบใจว่า "เรื่องนี้จะพูดถึงภายหลัง ตอนนี้ยังไม่ต้องกังวล" ซึ่งดีมาก แน่นอนว่าการเขียนเอกสารใช้เวลาและแรงมาก ดังนั้นบางครั้งการมีคำอธิบายเพียงบางส่วนก็ยังดีกว่าไม่มีเลย แต่ก็คิดว่าเอกสารสำหรับนักพัฒนามือใหม่ควรเขียนด้วยความใส่ใจในระดับเดียวกับเอกสารสำหรับคนที่ไม่ใช่นักพัฒนา
    • รู้สึกว่าบางคนชอบอ้างว่า ถ้าอะไรไม่ได้ถูกอธิบายให้ง่ายมากๆ ก็เป็นการ gatekeeping ทั้งที่มองข้ามข้อเท็จจริงว่าต่อให้ตัวเองรู้สึกยาก ก็ไม่ได้หมายความว่าจะเข้าใจทุกอย่างได้ทันทีโดยไม่มีความรู้พื้นฐานมาก่อน
    • ถ้าเป็น tutorial สำหรับนักพัฒนามือใหม่ และไม่ได้เขียนให้มืออาชีพอ่าน การคาดหวังให้อธิบายทุกแนวคิดอย่าง "Hoobijag" หรือ "shamrock portal" ทีละอย่างก็ดูแปลกๆ เพราะจริงๆ แล้วพวกเราทุกคนก็เริ่มจากการ google ศัพท์ที่ไม่รู้ทั้งนั้น

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

    • ลูกชายอายุ 17 ของตัวเองสนใจการเขียนโปรแกรมมาก ไม่นานมานี้เพิ่งสอนเรื่อง public/private/internal/static รวมถึง recursion ไป กำลังรอดูเงียบๆ ว่าคราวหน้าจะมีปฏิกิริยาอย่างไร
    • ไม่เห็นด้วยกับคำกล่าวที่ว่า "tutorial ส่วนใหญ่ไม่ได้มีไว้สำหรับคนที่ไม่ใช่นักพัฒนา" อยากย้ำว่าแค่พาดหัวของ tutorial นี้ก็ชัดเจนแล้วว่าตั้งใจพูดกับคนกลุ่มนั้นจริงๆ เสียงเรียกร้องว่าคู่มือติดตั้งพื้นฐานมากๆ ก็ควรทำให้ง่ายพอที่มือใหม่จะทำตามได้มีความสำคัญมาก เพราะการข้ามขั้นตอนเล็กๆ ในเรื่องที่ไม่คุ้นเคยอาจทำให้เสียเวลาไปหลายชั่วโมงได้
    • กลับกัน ไม่คิดว่าการเขียนเอกสารให้เป็นมิตรกับทุกคนมากขึ้นจะเป็นเรื่องเสียหาย เอกสารที่ดีมีประโยชน์ไม่เฉพาะกับมือใหม่ แต่กับนักพัฒนาด้วย เหตุผลที่เอกสารเข้าถึงง่ายไม่มีมากพอ ก็เพียงเพราะหลายคนไม่อยากลงแรงเพิ่มอีกนิด อีกทั้งเอกสารของนักพัฒนาก็ไม่เหมือนบทความวิชาการ เพราะมักสั้นเกินไป หรือผู้เขียนไม่ได้ใส่ใจผู้อ่าน สุดท้ายจึงกลายเป็นเอกสารที่ใช้ได้แค่กับผู้เชี่ยวชาญ ซึ่งถือว่าล้มเหลว
    • เห็นด้วยว่าควรมีเอกสารที่ค่อยๆ ปูบริบทให้ผู้เริ่มต้นอย่างเป็นขั้นเป็นตอน แต่อีกด้านหนึ่ง ช่วงนี้การปรับปรุง DX(developer experience) มักเน้นแต่ความ "ง่าย" จนยอมเสียความสามารถที่มีประโยชน์เดิมไป เช่น การค้นหา log หรือข้อความ error ทำให้บางทีเหมือนออกแบบเพื่อมือใหม่อย่างเดียว แต่ผู้ใช้เดิมกลับใช้งานลำบากขึ้น
    • ทุกวันนี้ tutorial หลายชิ้นดูเหมือนเขียนขึ้นเพื่อบันทึกว่า "ฉันได้มีส่วนร่วมกับโปรเจกต์ X" มากกว่าจะช่วยคนอ่าน จริงๆ แล้วถ้าผู้เขียนกลับมาลองทำตาม tutorial ของตัวเองอีกครั้งหลังจากผ่านไป 3 เดือน เนื้อหาที่ตกหล่นจะชัดขึ้นมากและช่วยให้ปรับปรุงได้เยอะ

  • นักเขียนด้านเทคนิคจำนวนมากไม่ตระหนักถึง 'คำสาปของความรู้' อย่างแท้จริง เคยมีประสบการณ์บริหารกิลด์ WoW(World of Warcraft) มาก่อน มีคน 40 คนรวมตัวกันเข้าดันเจียนพร้อมกันและต้องร่วมมือกันจัดการบอสหลายตัว ซึ่งความผิดพลาดเล็กน้อยเพียงครั้งเดียวอาจทำให้ทั้งทีมตายหมดได้ เพราะอย่างนั้นทุกคนจึงมารวมกันใน Teamspeak เพื่ออธิบายกลยุทธ์ล่วงหน้าให้ครบถ้วน บทเรียนสำคัญที่สุดตอนนั้นคือ "ให้สมมติว่าอีกฝ่ายไม่รู้ว่ากำลังพูดถึงอะไร" และ "สิ่งที่พูดไปแล้วก็ต้องพูดซ้ำอีก" คนส่วนใหญ่มักไม่ขัดจังหวะเพื่อถามแม้จะไม่รู้ ดังนั้นการคอยถามตัวเองว่า 'คำที่กำลังใช้อยู่นี้อีกฝ่ายรู้ไหม' หรือ 'เขาอาจไม่รู้แนวคิดนี้หรือเปล่า' แล้วสอดคำอธิบายเพิ่มเข้าไป จึงได้ผลอย่างมหาศาล ประสบการณ์การสื่อสารแบบนี้ใช้กับ technical communication ได้ตรงตัว และถ้าฝึกให้พ้นจาก 'คำสาปของความรู้' จนติดเป็นนิสัย ก็จะช่วยเพิ่มความเข้าใจของผู้อื่นได้มาก

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

  • หน้าโฮมโปรเจกต์จำนวนมากหรือ GitHub README หลายอันเขียนราวกับว่า "คนที่อ่านรู้อยู่แล้วทุกอย่าง" เวลาดูเอกสาร จึงอยากเห็นความใส่ใจมากขึ้นในเรื่องอย่าง 'ทำไมต้องใช้เครื่องมือนี้', 'มันแก้ปัญหาอะไร', 'ต่างจากเครื่องมือคล้ายกันอื่นๆ อย่างไร', 'ยังมีการใช้งานต่อเนื่องอยู่ไหม', 'มีข้อมูลพอให้ตัดสินใจเปรียบเทียบข้อดีข้อเสียได้เองหรือไม่' แค่ใช้เวลา 5 นาทีคิดว่า "ต่อให้เป็นมือใหม่ เขาจะสงสัยอะไรบ้าง" แล้วเขียนสิ่งนั้นลงไป ก็ช่วยให้เข้าถึงได้มากขึ้นมาก ต่อให้เป็นโปรเจกต์ที่ใช้เวลาหลายปีสร้างขึ้นมา ก็น่าเสียดายมากหากสุดท้ายเกิดสถานการณ์ที่ 'ผู้ใช้ล้มเลิกเพราะความยุ่งยาก โดยที่เจ้าของโปรเจกต์ไม่รู้ด้วยซ้ำว่าเขาเคยมาถึงตรงนี้แล้ว' และการเข้าใจบทบาทของเอกสารแต่ละประเภทก็สำคัญมากเช่นกัน https://diataxis.fr/ เป็นจุดเริ่มต้นที่ดี

    • ในสาย ROS(ซอฟต์แวร์หุ่นยนต์) มักเครียดกับ README ที่ขาดข้อมูลมากๆ อยู่เสมอ นอกจากชื่อโปรเจกต์แล้วแทบไม่มี hint อะไรเลย จนบ่อยครั้งยากแม้แต่จะเดาว่าเอาไว้ทำอะไร นี่ไม่ใช่ปัญหาเฉพาะโอเพนซอร์ส ที่ทำงานก็เจอเหมือนกัน และเหมือนจะมีแค่ตัวเองคนเดียวที่ลุกขึ้นมาเพิ่มคำอธิบายใน README ยุค monorepo สมัยก่อนกลับดูมีความสุขกว่าเสียอีก
    • เข้าใจว่าเป็นเครื่องมือที่นักพัฒนาสร้างขึ้นด้วยความรักและแรงกาย แต่ถ้าใส่ใจเรื่องเอกสารอีกนิด อุปสรรคในการเริ่มต้นจะต่ำลงมาก และถ้าเอกสารของคอมโพเนนต์อื่นๆ ที่ประกอบเป็น stack นั้นอ่านยากด้วย เส้นโค้งการเรียนรู้ก็จะชันขึ้นแบบทวีคูณ
    • เคยมีโปรเจกต์บน HN เมื่อก่อนที่ถึงขั้นไม่ได้เขียนด้วยซ้ำว่า "มันคืออะไร"

  • สิ่งสำคัญที่สุดในการเขียนเอกสารคือการกำหนด 'ระดับความรู้ของผู้อ่านเป้าหมาย' ให้ชัด จะตั้ง baseline ไว้สูงหรือต่ำก็ได้ แต่ถ้าเนื้อหาเบี่ยงจาก baseline มากเกินไป ผู้อ่านบางส่วนต้องไม่พอใจแน่นอน ในสถานการณ์แบบนี้ จะเลือกแก้ตัวหรือจะหาทางแก้ปัญหาก็ได้ ความจริงแล้วเดี๋ยวนี้ไม่ว่าจะ AI, Google หรือหนังสือ ก็ใช้ค้นหาสิ่งต่างๆ ได้ทันที ถ้าอยากรู้ว่า 'Shoobababoo คืออะไร' หรือ 'ทำไมต้องใช้ quagmire' ก็แค่ค้นหา แน่นอนว่าในอุดมคติ เอกสารควรเขียนให้พึ่งพาตัวเองได้มากที่สุดโดยไม่ต้องอาศัยข้อมูลภายนอก แต่โลกความจริงไม่ได้มอบความใส่ใจแบบนั้นให้เสมอไป

    • เพราะอย่างนี้ แนวโน้มของคู่มือการตั้งค่าหลายๆ อันที่เริ่มจาก "ดับเบิลคลิกไฟล์ exe แล้วกด next ต่อไป" จึงยิ่งเป็นปัญหา การตั้ง baseline ของคู่มือสำคัญมากจริงๆ
    • ตัวเองเขียนเอกสารสำหรับระบบภายในที่อ่อนไหวเป็นหลัก บางครั้งก็ระบุไว้ชัดเจนตั้งแต่ต้นว่า "คู่มือนี้สมมติว่าคุณรู้วิธีใช้ x, y, z อยู่แล้ว ถ้าไม่รู้ คุณไม่ควรทำงานนี้" แม้สิทธิ์เข้าถึงจะถูกจำกัดอยู่แล้ว แต่เผื่อกรณีอย่างสถานการณ์ DR ที่คนไม่คุ้นเคยอาจต้องมาใช้ ก็จงใจทิ้งเส้นแบ่งไว้ว่า 'ถ้าคุณยังไม่เข้าใจขนาดนี้ ห้ามทำเด็ดขาด'

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

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

  • ไม่นานมานี้ลอง deploy แอปจาก Gitlab ไปยัง DigitalOcean Kubernetes พบว่าต้องไปใช้งานเครื่องมือ third-party 3-4 ตัวโดยไม่มีคำอธิบายเลยว่าแต่ละตัวทำอะไร และยังต้องกรอกชื่อหรือ path ที่จะพิมพ์ใน command line เองทั้งหมด ไม่มีคำอธิบายด้วยว่าอะไรคือค่ามาตรฐานหรือควรให้ตรงกับอะไร ทั้งที่ตัวเองก็มีทักษะ Docker ค่อนข้างดี แต่เอกสารของเครื่องมือเหล่านี้ไม่เป็นมิตรจนแทบรู้สึกว่าไม่มีเอกสารเลยน่าจะดีกว่า

  • เหตุผลหลักที่เลิกเขียนหนังสือแล้วหันมาทำเว็บไซต์ tutorial คือมันเปิดโอกาสให้คนจำนวนมากเข้าถึงได้ง่ายขึ้นด้วยเครื่องมือเชิงโต้ตอบหลากหลายแบบ (เช่น องค์ประกอบ <abbr>) ถึงอย่างนั้นก็ยังหงุดหงิดที่คอนเทนต์บนเว็บทุกวันนี้ยังติดอยู่กับความสามารถแบบหนังสือกระดาษ ทั้งที่มีฟีเจอร์อย่างการคลิก การ hover การพับส่วนต่างๆ วิดีโอ หรือการตอบสนองของผู้ใช้มากมาย แต่กลับยังเต็มไปด้วยข้อความยาวเป็นกำแพงเหมือนเดิม แม้แต่ OP เองก็ยังใช้วิธีให้คลิกเชิงอรรถแล้วเลื่อนหน้าลงไปด้านล่าง ซึ่งให้ความรู้สึกว่าไม่ได้ใช้ศักยภาพของเว็บอย่างเต็มที่

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

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

    • น่าแปลกดีที่ทุกวันนี้สูตรอาหารออนไลน์(cookbook) กลับมักมีเรื่องเล่าจิปาถะที่ไม่จำเป็นมากกว่าบล็อกของคนที่ไม่ใช่นักพัฒนาเสียอีก