README ที่ยาว 95 หัวข้อ และเหตุผลที่มันคุ้ม

README ของ IQ Tutor ตอนนี้มีมากกว่า 95 หัวข้อ มีเลขกำกับทุกหัวข้อ และยาวจนไม่มีใครอ่านรวดเดียวจบ

ซึ่งไม่ใช่ปัญหา เพราะมันไม่ได้ถูกออกแบบมาให้อ่านรวดเดียวจบ

มันไม่ใช่เอกสาร มันคือ changelog ที่มีเหตุผล

แต่ละหัวข้อไม่ได้เขียนว่า "ฟีเจอร์นี้ทำอะไร" แต่เขียนว่า "ทำไมถึงออกแบบแบบนี้" รวมถึงบั๊กที่ทำให้ต้องออกแบบแบบนั้น

ตัวอย่างที่ชัดที่สุดคือเรื่อง rich menu ของ LINE มีสองหัวข้อแยกกันที่บันทึกไว้ว่า เมนูที่สร้างจากหน้า LINE Official Account Manager จะใช้กับระบบนี้ไม่ได้เลย เพราะมันไม่มี id ของ Messaging API

ผมเสียเวลาไปกับเรื่องนี้ครั้งหนึ่ง ถ้าไม่ได้เขียนไว้ ผมหรือใครก็ตามที่มาต่อจะเสียเวลาแบบเดียวกันอีก

ทำไมถึงคุ้ม

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

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

ความไม่สม่ำเสมอบางอย่างในระบบไม่ใช่บั๊ก มันคือการตัดสินใจทางธุรกิจที่เคยถกกันมาแล้ว ถ้าไม่มีบันทึก มันจะหน้าตาเหมือนบั๊กทุกครั้งที่กลับมาอ่าน

กฎที่ใช้

เขียนทุกครั้งที่ ship ฟีเจอร์ใหม่ได้หัวข้อใหม่ ส่วนการแก้บั๊กหรืองานต่อเนื่องจะต่อท้ายหัวข้อเดิมที่เกี่ยวข้อง ไม่มีข้อยกเว้น

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

แยกตามผู้อ่าน README คือเหตุผลและประวัติสำหรับคนเขียนโค้ด ส่วน FEATURES.md คือรายการ "ระบบทำอะไรได้บ้าง" ภาษาคน สำหรับเจ้าของ และ GitBook คือคู่มือทีละขั้นพร้อมภาพหน้าจอสำหรับแอดมิน ติวเตอร์ และผู้ปกครอง คนละกลุ่ม คนละเอกสาร

คอมเมนต์ในโค้ดบอก "ทำไม" ไม่ใช่ "อะไร" บรรทัดถัดไปทำอะไร โค้ดบอกเองได้อยู่แล้ว

ข้อเสียที่ยอมรับ

ไฟล์มันใหญ่มาก การหาอะไรสักอย่างต้องพึ่งการค้นหา ไม่ใช่การอ่านไล่ และการเขียนแต่ละครั้งกินเวลาจริง — บางทีพอ ๆ กับเวลาที่ใช้เขียนฟีเจอร์เล็ก ๆ

แต่ต้นทุนของการแก้บั๊กเดิมซ้ำสองนั้นแพงกว่าเสมอ โดยเฉพาะเมื่อมันอยู่บน production ที่มีเงินจริงวิ่งอยู่