กฎสำหรับการเขียนซอฟต์แวร์ทิวทอเรียล

• ทิวทอเรียลซอฟต์แวร์ส่วนใหญ่มักละเลยรายละเอียดสำคัญ หรือมีสมมติฐานแฝงที่ไม่ตรงกับความคาดหวังของผู้อ่าน ทำให้ผู้อ่านไม่สามารถทำตามขั้นตอนซ้ำได้
• หากทำตามกฎง่าย ๆ เพียงไม่กี่ข้อ การเขียนทิวทอเรียลที่ยอดเยี่ยมก็ง่ายกว่าที่คิด

กฎ

1. เขียนสำหรับผู้เริ่มต้น
2. ตั้งชื่อเรื่องที่สัญญาผลลัพธ์อย่างชัดเจน
3. อธิบายเป้าหมายในบทนำ
4. แสดงผลลัพธ์สุดท้ายให้ดูล่วงหน้า
5. เขียนโค้ดสไนเป็ตที่คัดลอก/วางได้
6. ใช้ long flags ในคำสั่ง
7. แยกค่าที่ผู้ใช้กำหนดเองออกจากตรรกะที่นำกลับมาใช้ซ้ำได้
8. ลดภาระของผู้อ่าน
9. เขียนให้โค้ดอยู่ในสภาพที่ใช้งานได้เสมอ
10. สอนเพียงหัวข้อเดียว
11. ให้ความชัดเจนมาก่อนการตกแต่ง
12. ลด dependencies ให้เหลือน้อยที่สุด
13. ระบุชื่อไฟล์ให้ชัดเจน
14. ใช้หัวข้อที่สม่ำเสมอและสื่อความหมาย
15. พิสูจน์ว่าโซลูชันใช้งานได้จริง
16. ลิงก์ไปยังตัวอย่างแบบสมบูรณ์

เขียนสำหรับผู้เริ่มต้น

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

ตั้งชื่อเรื่องที่สัญญาผลลัพธ์อย่างชัดเจน

• ชื่อเรื่องควรสื่ออย่างเจาะจงว่าผู้อ่านจะได้เรียนรู้อะไรจากทิวทอเรียล
• หลีกเลี่ยงชื่อเรื่องที่ไม่ชัดเจนหรือคลุมเครือ และอธิบายผลลัพธ์ที่คาดหวังให้ชัด
  • ตัวอย่าง: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

อธิบายเป้าหมายในบทนำ

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

แสดงผลลัพธ์สุดท้ายให้ดูล่วงหน้า

• ให้แสดงเดโมหรือภาพหน้าจอของสิ่งที่ผู้อ่านจะสร้างจากทิวทอเรียลให้เร็วที่สุดเท่าที่ทำได้
  • การแสดงผลลัพธ์สุดท้ายตั้งแต่ต้นช่วยให้เป้าหมายชัดเจน
• ตัวอย่าง: แสดงภาพหน้าจอของผลิตภัณฑ์สุดท้าย, UI, หรือตัวอย่างการทำงาน

เขียนโค้ดสไนเป็ตที่คัดลอก/วางได้

• เขียนให้ผู้อ่านสามารถคัดลอกโค้ดไปวางใน editor หรือ terminal แล้วรันได้ง่าย
• ตัดองค์ประกอบที่ไม่จำเป็น เช่น อักขระ prompt ของ terminal อย่าง $ ออก
• ใช้ non-interactive flags เพื่อลดความซับซ้อนของคำสั่ง และใช้ && เพื่อให้หยุดเมื่อเกิดข้อผิดพลาด

ใช้ long flags ในคำสั่ง

• ในคำสั่งควรใช้ long flags ที่สื่อความหมายชัดเจนแทน short flags เพื่อให้ผู้เริ่มต้นเข้าใจได้ง่าย
  • ใช้ --recursive แทน -r

แยกค่าที่ผู้ใช้กำหนดเองออกจากตรรกะที่นำกลับมาใช้ซ้ำได้

• แยกให้ชัดเจนระหว่างค่าที่ผู้ใช้ต้องแก้ไข กับโค้ดที่ไม่ควรถูกแก้ไข
• ใช้ environment variables เพื่อกำหนดค่าที่ปรับแต่งได้และเพิ่มความอ่านง่ายของโค้ด

ลดภาระของผู้อ่าน

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

เขียนให้โค้ดอยู่ในสภาพที่ใช้งานได้เสมอ

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

สอนเพียงหัวข้อเดียว

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

ให้ความชัดเจนมาก่อนการตกแต่ง

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

ลด dependencies ให้เหลือน้อยที่สุด

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

ระบุชื่อไฟล์ให้ชัดเจน

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

ใช้หัวข้อที่สม่ำเสมอและสื่อความหมาย

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

พิสูจน์ว่าโซลูชันใช้งานได้จริง

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

ลิงก์ไปยังตัวอย่างแบบสมบูรณ์

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

[godogi7]

สำหรับอ้างอิง

[wedding]

ขอปักหมุดอันนี้ไว้ก่อน!

[ilikeall]

เป็นบทความที่ดีนะครับ

[halfenif]

ช่วงนี้ได้ลองทำตามบทเรียนของ dagster แล้วรู้สึกว่าทำออกมาได้ดีมาก

https://courses.dagster.io/

[aer0700]

ฉันลองดูบทแนะนำของ Dagster มาคร่าว ๆ แล้ว ดีมากเลยครับ
ส่วนบทแนะนำของ Django เนื้อหาแน่นก็จริง แต่ยาวเกินไปสำหรับผม เลยค่อนข้างไม่ชอบนิดหน่อย อยากให้แบ่งย่อยกว่านี้ครับ

[savvykang]

มีกรณีศึกษาของบทแนะนำที่ทำได้ดีอย่าง Django เช่นกัน https://docs.djangoproject.com/en/5.1/intro/tutorial01/

[jhj0517]

ใช้ภาษาที่เข้าใจง่าย & แสดงผลลัพธ์สุดท้ายให้ดูก่อนเป็นอันดับแรก.

[aer0700]

แทนที่จะแสดงวิธีใช้งานพื้นฐานอันน่าเบื่อของเฟรมเวิร์ก
บางครั้งก็มักมีเอกสารสอนใช้งานที่อยากโชว์ว่าเฟรมเวิร์กนี้เจ๋งแค่ไหนมากกว่า
พอกดเข้าไปที่ Get started แล้วเจอว่าแปะป้ายว่าเป็นบทสอนการใช้งานพื้นฐาน แต่ดันเป็นเอกสารยาว 10 หน้า นี่ไม่ชอบมากครับ

[beenzinozino]

แต่ละคนโหดกันสุดๆ...

[savvykang]

https://tanstack.com/table/latest/docs/introduction

[nono9633]

https://github.com/tmux/tmux/wiki/Getting-Started