Diátaxis – แนวทางเชิงระบบสำหรับการเขียนเอกสารทางเทคนิค
(diataxis.fr)- โดยตั้งอยู่บนสมมติฐานว่าเอกสารทางเทคนิคต้องทำหน้าที่แตกต่างกันไปตามบริบทของผู้ใช้ Diátaxis จึงเป็นแนวทางที่จัดระเบียบทั้ง เนื้อหา·โครงสร้าง·รูปแบบ ไปพร้อมกัน
- แบ่งความต้องการของผู้ใช้ออกเป็น 4 แบบ และจับคู่กับประเภทเอกสาร tutorials, how-to guides, technical reference, explanation
- ไม่ได้เป็นเพียงตารางจัดหมวดหมู่ แต่ใกล้เคียงกับ กรอบการออกแบบเอกสาร ที่ครอบคลุมว่าจะเขียนอะไร เขียนอย่างไร และวางไว้ที่ไหน
- ทำให้นักเขียนและผู้ดูแลรักษาเอกสารประเมินคุณภาพเอกสารได้ง่ายขึ้น อีกทั้งยังมีข้อดีคือเบา เข้าใจง่าย ใช้งานอย่างเป็นธรรมชาติ และไม่บังคับวิธีการ implement แบบใดแบบหนึ่ง
- เช่นกรณีของ Vonage, Gatsby และ Cloudflare ซึ่งสามารถนำไปใช้เป็นเกณฑ์เชิงปฏิบัติสำหรับทีมที่ต้องการปรับปรุงความสามารถในการค้นหาเอกสารและโครงสร้างข้อมูล
เอกสาร 4 ประเภทที่ Diátaxis แบ่งไว้
- Diátaxis เป็นทั้ง วิธีคิดและวิธีปฏิบัติ สำหรับการเขียนและดูแลเอกสารทางเทคนิค
- จุดตั้งต้นคือการทำความเข้าใจความต้องการของผู้ใช้เอกสาร แล้วจึงสกัดหลักการเกี่ยวกับเนื้อหา สถาปัตยกรรม และรูปแบบจากจุดนั้น
- ความต้องการและรูปแบบของเอกสารถูกแบ่งออกเป็น 4 แบบ
-
tutorials
-
how-to guides
-
technical reference
- explanation
- ตัวเอกสารเองก็ควรถูกจัดระเบียบโดยยึดความต้องการทั้ง 4 แบบนี้เป็นศูนย์กลาง และ Diátaxis พิจารณา 3 คำถามไปพร้อมกัน
- content: จะเขียนอะไร
- style: จะเขียนอย่างไร
- architecture: จะจัดโครงสร้างอย่างไร
-
การประยุกต์ใช้สำหรับผู้เขียนและผู้ดูแลรักษา
- Diátaxis เป็นแนวทางที่ช่วยได้ไม่เฉพาะผู้ใช้เอกสาร แต่รวมถึงผู้เขียนและผู้ดูแลรักษาเอกสารด้วย
- เบาและเข้าใจง่าย
- นำไปใช้ได้อย่างเป็นธรรมชาติ
- ไม่บังคับข้อจำกัดด้าน implementation
- มอบ หลักการด้านคุณภาพ ที่ช่วยให้ผู้ดูแลรักษาประเมินงานของตนเองได้
- หลักการนี้ถูกสรุปขึ้นจากการนำไปใช้สำเร็จในโครงการเอกสารนับร้อยโครงการ
กรณีศึกษาจากโครงการเอกสารจริง
- Greg Frileux จาก Vonage ประเมินว่า Diátaxis ช่วยให้สร้างชุดเอกสารภายในที่ผู้ใช้ชื่นชอบและผู้ร่วมพัฒนาก็สามารถเพิ่มเนื้อหาได้ง่าย
- Gatsby ระบุว่าเมื่อปรับโครงสร้างเอกสารโอเพนซอร์สใหม่ ได้ใช้กรอบ Diátaxis เป็นทรัพยากรหลัก และทั้ง 4 ด้านช่วยในการจัดลำดับความสำคัญของเป้าหมายผู้ใช้สำหรับเอกสารแต่ละประเภท
- Cloudflare ใช้ Diátaxis เป็นเกณฑ์ของ information architecture ในการออกแบบ Cloudflare developer docs ใหม่ และอ้างอิงกรอบนี้เมื่อต้องตัดสินใจว่าเนื้อหาใหม่ควรถูกวางไว้ตรงไหน
1 ความคิดเห็น
ความคิดเห็นจาก Hacker News
แม้จากมุมมองของคนที่ไม่ได้เขียนงานอย่างมืออาชีพ ข้อคิดที่สำคัญและพื้นฐานที่สุดที่ได้จากเรื่องนี้ โดยไม่เกี่ยวกับรายละเอียดปลีกย่อย คือ ไม่จำเป็นต้องพูดทุกอย่างให้ถูกต้องแม่นยำเพียงครั้งเดียวเท่านั้น
ก่อนจะเจอแนวคิดนี้ ผมเคยทำให้ตัวเองสับสนเพราะคิดว่าลำดับการไหลของข้อความหนึ่งชุดต้องทำหน้าที่เป็น “เอกสารทั้งหมด”
แค่ตระหนักว่าคุณสามารถเขียนข้อมูลเดียวกันในรูปแบบที่ต่างกันสำหรับผู้อ่านแต่ละกลุ่มได้ ก็ช่วยได้มากแล้ว
เพราะผู้อ่านจะมองหาตัวหารร่วมระหว่างตัวอย่างเหล่านั้น ทำให้กำกวมน้อยกว่าการอธิบายด้วยตัวอย่างเดียว
ผู้เขียนอย่างซาโลมอนในหนังสือสุภาษิตของคัมภีร์ไบเบิลก็ใช้เทคนิคนี้อยู่บ่อยครั้ง
ในบทคัดย่ออาจเขียนว่า “บทความนี้ประเมิน Y กับ Z และแสดงให้เห็นว่า X เป็นจริง” ในบทนำก็อธิบายว่าปัญหาของ A สำคัญเพราะ B แต่แง่มุม X ถูกมองข้าม และเมื่อประเมิน Y จะเผยให้เห็นความท้าทายในโลกจริงที่ต่างจาก Z จากนั้นสรุปอีกครั้งว่า “กล่าวโดยย่อ Y ดีกว่า Z เพราะ X”
ในงานที่เกี่ยวข้องก็จะต่อด้วยว่าแนวทางของ Z ปรับปรุงอะไรบ้าง แต่ยังไม่เพียงพอดังที่จะเห็นในภายหลัง และในแต่ละส่วนก็จะวนกลับมาพูดถึงสารหลักซ้ำไปมาอยู่เรื่อย ๆ
เมื่อ 2 สัปดาห์ก่อน ผมนำเฟรมเวิร์กนี้ไปใช้กับเอกสารของ Sequin และแค่ การมีกรอบ ก็ยอดเยี่ยมมากแล้ว
ตอนนี้ลำดับการไหลของเอกสารดีขึ้นมาก และเพราะรู้ว่าควรใส่อะไรไว้ตรงไหน การเพิ่มและดูแลเอกสารจึงง่ายขึ้นด้วย
แต่ที่น่าขันคือ เอกสารของ Diátaxis เองค่อนข้างเข้าใจยากและเยิ่นเย้อ ผมต้องอ่านหลายรอบถึงจะเริ่มจับทางได้
ตอนอธิบายให้ทีมฟัง ผมเปรียบเทียบกับการซื้ออุปกรณ์ทำอาหารอย่างหม้ออัดแรงดัน: เริ่มจาก quick start (บทเรียนสอนใช้งาน) เพื่อดูคร่าว ๆ ว่าจะไปจาก A ไป B ได้อย่างไร จากนั้นค่อยค้นหาว่าจะทำเมนูเฉพาะที่ชอบอย่างไร ซึ่งก็คือ how-to เมื่อมีรายละเอียดที่สงสัยก็ไปดูข้อมูลอ้างอิงเพื่อเช็กเวลาปรุงที่แน่นอนของถั่วแต่ละชนิด และเมื่ออยากรู้ไปถึงว่าทำไมแรงดันจึงเปลี่ยนเวลาปรุงอาหาร หรือระบบความปลอดภัยทำงานอย่างไร จึงค่อยอ่านเอกสารอธิบาย
ที่ตลกคือเอกสารของเรากลับหัวกลับหางอย่างสิ้นเชิง และเริ่มด้วยคำอธิบายอย่าง “How Sequin Works”
แรงกระตุ้นตามธรรมชาติของวิศวกรคืออยากพูดถึงหลักการทำงานและเหตุผลที่สร้างมันแบบนี้ก่อน เพื่อปลูกฝัง mental model ให้คนอ่าน แต่ผู้คนไม่มีเวลาและความอดทนขนาดนั้น
ควรพาผู้อ่านปรับตัวเข้ากับโลกของเราด้วยลำดับ quick start → how-to → ข้อมูลอ้างอิง แล้วเมื่อได้ความสนใจจริง ๆ ค่อยใช้เอกสารอธิบายเพื่อโน้มน้าวแนวทางของเรา
https://sequinstream.com/docs
เอกสารมักทำให้คลุมเครือด้วยคำพูดไร้สาระอย่าง “ประสบการณ์ซินเนอร์จีเชิงนวัตกรรม” ราวกับบริษัทอายที่จะยอมรับว่าเครื่องมือของตัวเองก็เป็นเพียงเครื่องมือ หรือไม่ก็ลงรายละเอียดเฉพาะเจาะจงเกินไปก่อนจะพูดถึงว่า “ผลิตภัณฑ์นี้มีอยู่ไปทำไม”
แต่ในเอกสารมีคำว่า CDC โผล่ซ้ำ ๆ และผมต้องไปค้นหาคำจำกัดความ แม้ในอาชีพผมจะเคย implement CDC มาหลายครั้ง แต่ไม่คุ้นกับตัวย่อนี้
ท้ายที่สุดแล้ว flow เป็นสิ่งที่ผู้อ่านเลือกเอง และหัวของผมทำงานแบบต้องการคำอธิบายภาพรวมก่อน แล้วจึงค่อยหา how-to กับบทเรียนสอนใช้งาน
จากมุมมองของนักเขียนเอกสารเทคนิค Diátaxis คล้ายกับ DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
แต่ระบบแบบนี้อาจพลาดสิ่งที่ผู้ใช้ต้องการจริง ๆ ได้
หากเอกสารเทคนิคถูกใช้เฉพาะในแพลตฟอร์มเอกสาร Diátaxis อาจเหมาะไปได้นาน แต่ถ้าข้อมูลเดียวกันอาจถูกใช้ และควรถูกใช้ ในหลายที่ เช่น UI, พอร์ทัลเอกสาร, แอปมือถือ ก็อาจต้องแบ่งข้อมูลออกเป็นชิ้นเล็กลงแล้วประกอบเข้าด้วยกันได้หลายวิธี
สิ่งนี้เรียกว่า การนำคอนเทนต์กลับมาใช้ซ้ำ คือวิธีใช้คอนเทนต์เดียวกันในหลายตำแหน่ง
หนึ่งในแนวทางการเขียนและแก้ไขข้อมูลเพื่อการนำคอนเทนต์กลับมาใช้ซ้ำอธิบายไว้ในแนวคิด “every page is page one”: https://everypageispageone.com/the-book/
หากมีทรัพยากรและเวลา แนะนำให้ทำ UX research ตั้งแต่ช่วงเริ่มโครงการ เพื่อหลีกเลี่ยงสถานการณ์อึดอัดในภายหลังจาก information model ที่จำกัดเกินไป
Nielsen/Norman ก็ศึกษาเรื่องนี้ไว้มาก และเสนอแนวทางที่น่าสนใจสำหรับแก้ปัญหาที่เกี่ยวข้อง: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA แยกประเภทหัวข้อ เช่น งาน ข้อมูลอ้างอิง แนวคิด แต่บทเรียนสอนใช้งานหรือคู่มือโซลูชันจะเป็นการผสมผสานของประเภทหัวข้อเหล่านั้น
ในที่นี้ดูเหมือนโฟกัสอยู่ที่ผลลัพธ์ที่ใหญ่กว่าหัวข้อเดี่ยว ๆ
และสงสัยด้วยว่าเพราะลงลึกกับ DITA มาก ความซับซ้อนจึงไม่เป็นปัญหาหรือไม่
ถ้าแบ่งคอนเทนต์เป็นชิ้นที่นำกลับมาใช้ซ้ำได้ แล้วทำเครื่องหมายด้วย semantics ของ DITA หรือ DocBook ก็น่าจะทำให้โมเดลภาษาขนาดใหญ่ “เข้าใจ” ได้ง่ายขึ้นมาก แต่ผมยังไม่เคยเห็นข้อมูลที่เกี่ยวข้อง
ทุกวันนี้มีวิธีเขียนเอกสารที่ดีกว่าการต้องไปปล้ำกับ XSL/FO และญาติ ๆ ของมัน
ในสายการเขียนเอกสารทางเทคนิค แนวทางนี้ได้รับความนิยมมากอยู่แล้ว และค่อนข้างใกล้เคียงมาตรฐาน
เพียงแต่บางครั้งมีการผลักแนวคิดนี้ไปไกลเกินไป จนหน้าเอกสารมีแค่ สี่หมวดหมู่นี้ ตามตัวอักษร ซึ่งโดยทั่วไปมักใช้ไม่ได้ผลดี
ส่วนใหญ่มีประโยชน์ในการช่วยให้ผู้เขียนคงกรอบคิดไว้ได้ เช่น “นี่คือไกด์ ดังนั้นอย่าพยายามสอน แต่ให้โฟกัสที่การพาไปให้ถึงผลลัพธ์”
ในความเป็นจริง การมีเส้นแบ่งที่แข็งเกินไปไม่ใช่สิ่งพึงประสงค์ และการมีส่วนที่เป็น tutorial อยู่บ้างในไกด์ก็ไม่เป็นไร
จุดที่แนวทางนี้สะดุดจริง ๆ ผมมองว่าอยู่ที่การเชื่อมโยงระหว่างแต่ละควอดแรนต์ไม่เพียงพอ
ตัวอย่างเช่น ใน software framework หากไกด์ไม่ลิงก์ไปยัง reference ของคลาสหรือเมธอดเฉพาะที่ท้ายที่สุดต้องใช้ ก็จะสำรวจบริบทแวดล้อมได้ยากขึ้นมาก
เอกสารของเฟรมเวิร์กบางตัวแบ่งควอดแรนต์แบบนี้ และหนึ่งในเรื่องที่น่าหงุดหงิดที่สุดของเอกสารเหล่านั้นก็คือเรื่องนี้
หากไม่มีผู้เชี่ยวชาญคนอื่นอยู่ด้วย สำหรับมือใหม่ การทำตามกฎอย่างเคร่งครัดอาจดีกว่าการ “พยายามทำสิ่งที่ถูกต้องด้วยตัวเอง”
ตามนิยามแล้ว มือใหม่ไม่มีความเชี่ยวชาญพอจะตัดสินเรื่องนั้น และเมื่อมีประสบการณ์มากขึ้น ก็จะเริ่มเห็นว่าควรออกนอกกฎที่กำหนดไว้ตรงไหน
คล้ายความแตกต่างระหว่างการทำอาหารที่บ้านตามตำรา กับเชฟมืออาชีพที่โยนวัตถุดิบลงหม้อตามสัญชาตญาณและรสชาติ
แต่เคยทำงานกับคนที่ยืนยันว่าต้องทำตามกฎตามตัวอักษร ถึงขั้นบอกว่าใน tutorial ไม่ควรมีประโยคอธิบายแม้แต่ประโยคเดียว
ความเสี่ยงของระบบแบบนี้ก็อยู่ตรงนั้นเอง
คล้ายหลักการเขียนโปรแกรมอย่าง “อย่าเปลี่ยน global variable” หรือ “เขียนฟังก์ชันให้สั้น”
ไม่จำเป็นต้องทำให้สมบูรณ์แบบ แต่โดยมากแล้วการขยับไปในทิศทางนั้นย่อมดีกว่าทิศทางตรงข้าม
ผมจึงให้ Claude จัดประเภทส่วนด้านบนตาม Diátaxis แล้วมันตอบว่าส่วนใหญ่เป็นคำอธิบาย มีองค์ประกอบของ reference ปนอยู่บ้าง และไม่ถือว่าเหมาะตามเกณฑ์ของ Diátaxis
มันบอกว่าจะดีกว่าหากแยกเป็นส่วนที่อธิบายแนวคิดและความสำคัญของการปรับ hyperparameter อย่างล้วน ๆ กับส่วน reference แยกต่างหากที่แจกแจงเครื่องมือและวิธีที่ใช้ได้
แต่ต่อจากนั้นมันก็สรุปด้วยว่า เหตุใดแนวทางแบบรวมนี้จึงทำงานได้ดีในบริบทของ user guide: มันตามลำดับการเรียนรู้จริงของผู้คน เชื่อมแนวคิดกับการใช้งานทันที ค่อย ๆ เปิดเผยจากแนวคิดพื้นฐานไปสู่เครื่องมือที่ซับซ้อน และเชื่อมทฤษฎีกับงานปฏิบัติจนให้คุณค่าเชิงใช้งานจริง
ในฐานะคนที่เพิ่งปล่อยแอป SwiftUI ตัวแรกเสร็จ ผมรู้สึกอย่างแรงว่าในอุตสาหกรรมเทคโนโลยีสมัยใหม่ การทำเอกสาร ถูกปฏิบัติอย่างหละหลวมเกินไป
ผมคิดถึงผลงานของนักเขียนเอกสารทางเทคนิคชั้นยอดที่ Apple ไล่ออกไปมาก และวิศวกรของ Apple ก็เขียนเอกสารได้แย่มากจริง ๆ
อย่างไรก็ดี ผมระวังแนวทางแบบ “ยึดหลักคำสอน” อยู่เสมอ เพราะมันมักทำให้เกิด “ชนชั้นนักบวช” ที่ไม่ยอมยืดหยุ่นแม้ความจริงจะเรียกร้อง
คนที่สร้างหลักคำสอนนั้นขึ้นมาตอนแรกอาจใช้มันได้ยอดเยี่ยม แต่ “นักบวช” รุ่นหลัง ๆ อาจทำพังจนเปลี่ยนแนวทางให้กลายเป็นคำสาป
ไอเดียดี ๆ จำนวนมากถูกทำลายด้วยการนำไปใช้ที่แข็งทื่อเกินไป แค่ดูว่า “Agile” กลายเป็นอะไรไปแล้วก็พอ
โดยพื้นฐานแล้ว เอกสารมีสองหน้าคือสำหรับผู้ดูแลรักษาและสำหรับผู้ใช้ และทั้งสองมีความต้องการต่างกันมาก จึงอาจควรให้ทีมที่ต่างกันโดยสิ้นเชิงดูแล
แม้จะมีปัญหาเรื่องเอกสารหลายแห่งหลุดจากการซิงก์กัน แต่สิ่งสำคัญคือผลลัพธ์
หากสามารถซิงก์หลายอินสแตนซ์ได้อย่างมีประสิทธิภาพ เอกสารก็จะมีประสิทธิผลและเป็นประโยชน์ต่อผู้บริโภค
ต่อให้เอกสารถูกจัดรูปแบบและซิงก์อย่างสมบูรณ์แบบ แต่ถ้าไม่มีใครอ่านก็ไม่มีคุณค่า
ใน SNL ตัวละคร The Anal-Retentive Chef ที่ Phil Hartman แสดงใช้เวลากับการเตรียมการมากจนไม่ได้สาธิตการทำอาหารจริง ๆ ซึ่งผมเห็นภาพแบบนั้นมากในสายเทคโนโลยี
toolchain และไลบรารีอาจสมบูรณ์แบบ แต่ในทางปฏิบัติกลับใช้งานไม่ได้
เอกสารเป็นส่วนผสมของหลายสาขา ทั้งธรรมชาติและจิตวิทยาของมนุษย์ การออกแบบกราฟิก โครงสร้างข้อมูลสารสนเทศ โครงสร้างพื้นฐานทางเทคนิค การจัดพิมพ์และการเผยแพร่
ในโปรเจกต์ส่วนใหญ่ เอกสารถูกมองเป็นเรื่องทีหลัง แต่ผมคิดว่ามันควรเป็น ข้อพิจารณาระดับหนึ่ง ตั้งแต่ขั้นข้อกำหนด
เราอาจขุดลึกเรื่องโครงสร้างเอกสารได้ไม่รู้จบ แต่มันทำหน้าที่เป็นล้อช่วยพยุงที่ยอดเยี่ยม จนกว่าจะพบจุดที่มันรั่ว
ฟังดูเหมือนหมายความว่าความเข้าใจผิดทั่วไปหรือการนำไอเดียดีไปใช้ผิด ๆ ทำให้ตัวไอเดียนั้นเสียหายไปเอง
ตรงกันข้าม ยังมีประสบการณ์ที่ได้จากการนำไปใช้จริง หากไอเดียแรกเริ่มไม่ได้ดีจริง ก็เป็นการทำลายภาพลวงตา และตัวอย่างที่แย่ก็เผยให้เห็นความคลุมเครือที่เมื่อตีความผิดจะนำไปสู่ความล้มเหลว ทำให้ไอเดียนั้นละเอียดประณีตขึ้น
อย่างไรก็ตาม หากมีคนจำนวนมากคุ้นเคยกับการนำไปใช้ที่แย่ ความนิยมของไอเดียอาจลดลง และความต้องการ implementation ที่ประณีตก็อาจลดลงด้วย
เรื่องนี้ใกล้เคียงกับ โศกนาฏกรรมของแอนติคอมมอนส์ มากกว่าการเสื่อมถอยของตัวไอเดียเอง
Diátaxis ยอดเยี่ยมสำหรับการจัดโครงสร้างเอกสาร แต่คุณค่าที่แท้จริงอยู่ที่มันทำให้วิธีเขียนเอกสารเรียบง่ายขึ้น
มันช่วยให้เลิกคิดว่าจะยัดทุกอย่างลงใน “เอกสารที่สมบูรณ์แบบ” ฉบับเดียว และตระหนักว่าผู้ใช้แต่ละคนมีความต้องการต่างกัน
tutorial มีไว้เพื่อเรียนรู้ด้วยการทำตาม ไกด์มีไว้เพื่อแก้ปัญหาเฉพาะ reference มีไว้สำหรับค้นหาอย่างรวดเร็ว และคำอธิบายมีไว้ขุดลึกถึง “เหตุผล”
แค่ความชัดเจนนี้ก็ทำให้เขียนเอกสารที่มีประโยชน์ได้แล้ว
แต่ไม่ว่าระบบใด หากยึดแน่นเกินไปก็กลายเป็นกับดักได้
หรือมี paradigm ที่เป็นหนึ่งเดียวอยู่กันแน่ ผมก็สงสัย
องค์กรของเราใช้วิธีนี้อยู่ และหลังจากนำมาใช้ เอกสารทางเทคนิคก็ยกระดับไปคนละขั้นเลย
เมื่อเพิ่ม ความเป็นเจ้าของหน้าเอกสาร และการรีวิวตามรอบของเจ้าของแต่ละหน้าเข้าไปด้วย มันก็กลายเป็นงานทำเอกสารทางเทคนิคเพียงแบบเดียวที่ผมเคยเห็นว่าประสบความสำเร็จ
ผมมองว่าภาพที่ divio ใช้นั้นเข้าใจได้โดยสัญชาตญาณกว่ามาก: https://docs.divio.com/documentation-system/
เพียงแต่ฝั่ง Diátaxis ดูเหมือนจะจัดทำเอกสารอธิบายความหมายแต่ละส่วนไว้ครอบคลุมกว่า
เวอร์ชันที่ Diataxis.fr เขียนใหม่จาก Divio นั้นกราฟิกดูรกรุงรังน้อยกว่า แต่โดยแก่นแล้วผมมองว่าเหมือนกับที่ Divio ใช้
เท่าที่เกี่ยวกับไอเดียที่ทั้งสองแหล่งนำเสนอในบริบทของเว็บไซต์ของตน ผมมองมาตลอดว่าทั้งสองเป็นเอกสารเดียวกันโดยแทบจะเป็นเช่นนั้นจริง ๆ
อยากทราบว่าตรงไหนที่เข้าใจได้โดยสัญชาตญาณกว่า
ผมชอบไอเดียนี้ และโชคดีที่เคยพบคนที่สร้างมันขึ้นมาสองสามครั้งที่ PyConUK เขาเป็นคนมีความสามารถและใจดีมาก
แต่ผมยังมีข้อกังขากับการแบ่งแยกพื้นที่ต่าง ๆ ของเอกสารอย่างเคร่งครัดถึงขนาดนี้
เคยมีครั้งหนึ่งในสปรินต์ที่ผมถูกบอกว่าเอกสารที่ผมกำลังเตรียมอยู่นั้นยอมรับไม่ได้ เพราะผสมรูปแบบหลายแบบเข้าด้วยกัน ขอเสริมว่าไม่ใช่ Daniele ที่พูดแบบนั้น
ไม่ได้จะอ้างอำนาจอะไร แต่ผมทำงานเป็นครูมากว่า 20 ปี และพอมีความเข้าใจอยู่บ้างเกี่ยวกับวิธีอธิบายและวางโครงช่วยการเรียนรู้ เพื่อให้ผู้คนทำงานให้สำเร็จไปพร้อมกับค่อย ๆ สร้างความเข้าใจ
ตราบใดที่ไม่ยึดติดจนแข็งทื่อเกินไป นี่เป็นเครื่องมือที่ยอดเยี่ยมสำหรับตัดสินใจว่าจะสร้างเอกสารอย่างไร และเอกสารแต่ละประเภทควรทำหน้าที่อะไร
ผมมักเห็นกรณีที่สามารถเลือกตัวอย่างในเอกสาร เช่นใน numpy ได้ดีกว่านี้มาก แทนที่จะเป็นตัวอย่างแบบ “เวทมนตร์หล่นมาจากฟ้า”
ตัวอย่างเดียว ที่เลือกมาอย่างดีสามารถแสดงวิธีใช้งาน พร้อมทั้งให้การเรียนรู้มากมายถึงเคสขอบและข้อควรระวังได้
ในทางทฤษฎีผมคิดว่าถูก แต่เห็นด้วยได้ยาก คำต่าง ๆ ใกล้กันเกินไป
สำหรับผม “บทเรียนสอนใช้งาน”, “คู่มือวิธีทำ” และ “คำอธิบาย” แทบจะรู้สึกเหมือนเป็นคำพ้องความหมายกันในทางปฏิบัติ
ถ้าคิดลึก ๆ ก็เข้าใจว่าแต่ละหมวดมีเหตุผลรองรับ แต่เชิงความหมายมันใกล้กันเกินไปจนสมองมองไม่เห็นความแตกต่าง
เวลาผมอยากรู้ว่าบางอย่างทำงานอย่างไร แล้วเห็น “บทเรียนสอนใช้งาน” กับ “คู่มือวิธีทำ” ผมไม่รู้ว่าควรกดอะไร และก็แค่กดอันแรกไป
การลองหาถ้อยคำที่เข้ากับตัวเองมากกว่าก็อาจเป็นแบบฝึกหัดที่มีประโยชน์
หรืออาจทำความเข้าใจผ่านการแบ่งระหว่างการกระทำ/การรับรู้ คือ “ทำ vs คิด” และการได้มา/การนำไปใช้ คือ “กำลังเรียนรู้ vs กำลังทำงาน” ก็ได้
ยังมีหน้าที่แยกอธิบายความต่างระหว่างบทเรียนสอนใช้งานกับคู่มือวิธีทำโดยเฉพาะด้วย: https://diataxis.fr/tutorials-how-to/
หนึ่งในวิธีแบ่งที่ง่ายที่สุดคือ บทเรียนสอนใช้งานคือสิ่งที่ทำบน Stack Overflow ไม่ได้
บทเรียนสอนใช้งานคือกระบวนการที่ผู้เรียนเดินตามแผนการสอนที่ครูกำหนด และเติมเต็มส่วนที่ผู้เรียนยังไม่รู้ด้วยซ้ำว่าตนเองไม่รู้
บน Stack Overflow คุณต้องตั้งคำถาม แต่บทเรียนสอนใช้งานเป็นสื่อสำหรับคนที่ยังไม่รู้ด้วยซ้ำว่าควรถามอะไร
คำถามยอดนิยมจำนวนมากก็เป็นเรื่องว่าจะทำงานง่าย ๆ อย่างไร แต่ถ้าจะให้เข้ากับรูปแบบนั้น ต้องตั้งเป็นคำถาม ไม่ใช่ขอความช่วยเหลือแบบกว้าง ๆ: https://meta.stackoverflow.com/questions/284236
เอกสาร Diátaxis อธิบายความแตกต่างได้ค่อนข้างมีประสิทธิภาพ: บทเรียนสอนใช้งานคือประสบการณ์ที่มุ่งการเรียนรู้, คู่มือวิธีทำคือคำสั่งที่มุ่งเป้าหมาย, เอกสารอ้างอิงคือคำบรรยายทางเทคนิคที่มุ่งข้อมูล, และคำอธิบายคือการอภิปรายที่มุ่งความเข้าใจ
“บทเรียนสอนใช้งาน” ในระบบนี้ควรอ่านเป็น ศัพท์เฉพาะทาง ไม่ใช่คำในภาษาทั่วไป
คล้ายกับที่ “depression” ที่นักจิตวิทยาพูดถึงไม่ได้เหมือนกับความหมายในชีวิตประจำวันเสียทีเดียว
ถึงอย่างนั้นก็ยังดีกว่าการตั้งชื่อว่า Type I-IV tutorial
การบรรยายคือคำอธิบาย ส่วนบทเรียนสอนใช้งานหรือแล็บคือประสบการณ์ที่มีการชี้นำ และทำให้นึกถึง Contoso บริษัทสมมติของ Microsoft
คู่มือวิธีทำคือสิ่งที่ต้องใช้เวลาเสิร์ชหาวิธีแก้ หรือถาม ChatGPT ส่วนเอกสารอ้างอิงก็เป็นสิ่งอย่างพจนานุกรมคำพ้องความหมาย สารานุกรม หรือคู่มือผู้ใช้
วิดีโอเกมมีบทเรียนสอนใช้งานในตัว แต่พัซเซิลยาก ๆ ก็ยังต้องใช้บทสรุปแนวทางเล่น และการตั้งค่าปุ่มก็ดูจากเอกสารอ้างอิง