ตัวอย่างคือเอกสารที่ดีที่สุด

• เมื่อค้นหาเอกสาร นักพัฒนา 95% ต้องการเพียงตัวอย่างสั้น ๆ ก็เพียงพอ แต่กรณีที่สามารถหาตัวอย่างได้จากแหล่งทางการมีเพียง 5% เท่านั้น
• เอกสารทางเทคนิคอย่างเป็นทางการโดยพื้นฐานแล้วมักเขียนขึ้นโดย มุ่งเป้าไปที่คนที่จมอยู่กับ ecosystem นั้นอย่างลึกซึ้ง ทำให้นักพัฒนาที่ต้องสลับไปมาระหว่างหลายโปรเจ็กต์และหลายภาษาต้องใช้ พลังงานทางความคิดจำนวนมากในการกู้คืนบริบท
• หากดูเอกสารของฟังก์ชัน max() ใน Python จะพบว่ามี ความรู้พื้นฐานจำนวนมากที่ต้องมีเพื่อเข้าใจไวยากรณ์และแนวคิดของนิยามฟังก์ชัน แต่ถ้ามีตัวอย่างง่าย ๆ 5 บรรทัดก็เข้าใจได้ทันที
• clojuredocs.org ของชุมชน Clojure เป็นตัวอย่างที่ดีของเอกสารเชิงปฏิบัติที่มาจากตัวอย่างซึ่งผู้ใช้มีส่วนร่วมเพิ่มเข้าไป และยังรวมฟังก์ชันที่เกี่ยวข้องไว้ด้วย จึงช่วยให้ใช้งานจริงได้ดีขึ้น
• แม้แต่โปรเจ็กต์ซอฟต์แวร์ขนาดใหญ่เองก็ยัง ไม่ค่อยมีเอกสารครบทั้ง 4 ประเภท ทำให้นักพัฒนาต้องไปหาบทสอน ซึ่งไม่ใช่เพราะต้องการคำแนะนำ แต่เพราะ ต้องการตัวอย่าง

---

ความสำคัญของตัวอย่างเมื่อต้องค้นหาเอกสาร

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

วิเคราะห์กรณีเอกสาร Python

• ตัวอย่างฟังก์ชัน max() ในเอกสาร Python 3
  • max(iterable, /, *, key=None): คืนค่ารายการที่มีค่ามากที่สุด
  • จากนั้นตามด้วยคำอธิบายสั้น ๆ อีก 5 ย่อหน้า
• ความรู้ Python ที่ต้องมี เพื่อเข้าใจเอกสารนี้
  • ความหมายของ * ในนิยามฟังก์ชัน
  • ความหมายของ / ในนิยามฟังก์ชัน
  • แนวคิดของ "positional-only parameter separator"
  • แนวคิดของ iterable
  • แนวคิดของ keyword-only arguments
  • ความหมายทั่วไปของพารามิเตอร์ key
• ต้องอ่านข้อความก่อนจึงจะเข้าใจได้ว่า ควรส่งค่าอะไรและจะเรียกใช้ฟังก์ชันจริงอย่างไร

ผลของตัวอย่างที่เรียบง่าย

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

  max(4, 6) # → 6  
  max([1, 2, 3]) # → 3  
  max(['x', 'y', 'abc'], key=len) # → 'abc'  
  max([]) # ValueError: max() arg is an empty sequence  
  max([], default=5) # → 5  
  

• ตัวอย่างช่วยให้ เข้าใจได้ง่ายและเป็นธรรมชาติ

แนวปฏิบัติที่ดีจากชุมชน Clojure

• clojuredocs.org เป็นโปรเจ็กต์ที่ขับเคลื่อนโดยชุมชน Clojure
  • ผู้ใช้ช่วยกันเพิ่มตัวอย่างสำหรับฟังก์ชัน built-in
  • เป็น ทรัพยากรที่ขาดไม่ได้ ในการเขียนโค้ดประจำวัน
• หน้าตัวอย่าง: ดู into, spit, map เป็นต้น
• ลักษณะของตัวอย่าง
  • ไม่ได้มีเฉพาะฟังก์ชันนั้น แต่ยังรวมฟังก์ชันที่เกี่ยวข้องด้วย
  • ช่วยเพิ่มการใช้งานจริงและความเป็นประโยชน์เชิงปฏิบัติ

ข้อจำกัดของการทำเอกสารในปัจจุบัน

• แม้แต่โปรเจ็กต์ซอฟต์แวร์หลัก ๆ ก็ยัง ไม่ค่อยมีเอกสารครบทั้ง 4 ประเภท
  • อ้างอิง: ระบบเอกสารของ Divio
• เหตุผลที่ทำให้หลายคน ลังเลที่จะกดลิงก์ "Documentation"
  • เพราะส่วนใหญ่มักเป็น API reference ที่สร้างอัตโนมัติ กระชับเกินไป และอ่านยาก
• เหตุผลที่แท้จริงที่นักพัฒนามองหาบทสอน
  • ไม่ใช่เพราะต้องการคำแนะนำ แต่เพราะต้องการตัวอย่าง
  • บทสอนมีประโยชน์กว่าเพราะมีตัวอย่างรวมอยู่ด้วย

[sonnet]

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

[kuber]

ตัวอย่างคือเอกสารที่ดีที่สุด

มาที่ Go กันเถอะ ที่ซึ่งโค้ดก็คือเอกสาร~
พวกเราเปิดดู test code แล้วพัฒนากันได้แม้ไม่มี README

[pjtco]

ผมนึกว่ามีแค่ผมคนเดียวที่หัวไม่ดีพอจะอ่านเอกสารทางการแล้วไม่เข้าใจ 555
เอาจริง ๆ แค่โยนตัวอย่างมาให้แล้วอธิบายนิดหน่อยก็เข้าใจได้เร็วเลย.....

[nemorize]

งั้น PHP ก็คงเป็นได้ทั้งตัวอย่างที่ดีและตัวอย่างที่แย่ที่สุดเลยนะ

มันเป็นตัวอย่างที่ดีตรงที่ในเอกสารทางการสามารถอัปโหลดคอนเทนต์ที่ผู้ใช้มีส่วนร่วมได้ จึงดูตัวอย่างโค้ดที่หลากหลายได้

...แต่ก็เป็นตัวอย่างที่แย่ที่สุดตรงที่ PHP มี BC แบบละเอียดอ่อนของฟังก์ชันในตัวอยู่เยอะมาก และตัวอย่างที่มีคนช่วยกันเพิ่มเข้ามาก็ล้วนเป็นของเวอร์ชันสมัยโบราณ ทำให้มีสิ่งที่ต่างจากการทำงานจริงแบบละเอียดปนกันอยู่ จนยิ่งเพิ่มความสับสนเข้าไปอีก...555..55...

[savvykang]

เมื่อก่อนถ้าดูเอกสารพัฒนา iOS หรือ Cocoa จะมีส่วน use case แยกต่างหากอยู่ ซึ่งนั่นน่าจะเป็นวิธีทำเอกสารที่ถูกต้องไม่ใช่หรือ? ทั้งตัวอย่าง ลายเซ็นของฟังก์ชัน และคำอธิบายการทำงาน ล้วนจำเป็นทั้งหมด

[aer0700]

ตัวอย่างคือเอกสารที่ดีที่สุด

ถ้าเมื่อก่อนความขาดแคลนของ docs ทางการถูกเติมเต็มด้วย Stack Overflow และการค้นหาใน Google ทุกวันนี้ก็ดูเหมือนว่า LLM จะเข้ามาเติมเต็มแทน

[GN⁺]

ความคิดเห็นจาก Hacker News

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

  • จริง ๆ แล้วสิ่งที่คุณต้องการคือ type definition ต่างหาก type definition ทำหน้าที่เป็นเอกสารได้ดี เครื่องมือของระบบ type ทุกวันนี้แสดงข้อมูลจำนวนมากได้ทันทีใน editor หรือ IDE เลย ทำให้ความจำเป็นในการเปิดเอกสารมาอ่านเองลดลง ที่ช่วงหลังเอกสารแบบเน้นตัวอย่างมีมากขึ้นก็เพราะ workflow เปลี่ยนไปนั่นเอง เพราะมองว่าไม่จำเป็นต้องเขียนข้อมูลซ้ำในเอกสารอีก สำหรับสิ่งที่เครื่องมือด้าน type แสดงให้ได้อยู่แล้ว เวลาอ่านเอกสาร ฉันสนใจมากกว่าด้วยซ้ำว่า "เครื่องมือนี้ช่วยแก้ปัญหาอะไรได้บ้าง" และตัวอย่างก็ยอดเยี่ยมมากในการแสดงศักยภาพนั้น ถ้าต้องการแก้ปัญหาเฉพาะอย่าง การดูตัวอย่างช่วยให้ตัดสินได้เร็วว่าเครื่องมือนั้นมีประโยชน์หรือไม่ --- ถ้ามีระบบ type ฉันอยากดูตัวอย่างก่อน ถ้าไม่มีระบบ type ก็ 1) ไม่ค่อยพอใจ 2) อยากดูตัวอย่างก่อน แล้วค่อยตามด้วยคำอธิบายอาร์กิวเมนต์/ค่าที่คืนกลับ/โครงสร้างข้อมูลโดยละเอียด

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

  • ฉันไม่เห็นด้วยทั้งหมด เอกสารสไตล์ Javadoc คือเอกสารสำหรับการเขียนโปรแกรมที่อิงกับ type และ inline docstring ซึ่งจำเป็นต้องมีแน่นอน แต่จะไปดูบนเว็บก็ไม่จำเป็นเสมอไป เพราะดูจากโค้ดโดยตรงมีประสิทธิภาพกว่า ส่วนคู่มืออย่างตัวอย่างหรือ QuickStart นั้นจำเป็นจริง ๆ เพราะช่วยลดอุปสรรคในการเริ่มใช้ไลบรารี แค่มองโค้ดอย่างเดียวไม่ได้ทำให้รู้วิธีใช้ API ได้ง่าย ๆ เมื่อก่อนมีไลบรารี Java จำนวนมากที่ให้แค่ Javadoc ทำให้ใช้งานลำบากเพราะไม่รู้วิธีใช้

  • ฉันคิดว่าตัวอย่างที่ใส่คอมเมนต์ไว้อย่างดีคือสิ่งที่ดีที่สุด แต่ก็ไม่อาจมาแทนเอกสารแบบดั้งเดิมได้

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

• แม้แต่ man page ของ Unix ก็ต้องการตัวอย่างอย่างมาก โดยมากมันถูกเขียนเป็นเอกสารอ้างอิงสำหรับคนที่รู้เครื่องมือนั้นดีอยู่แล้ว เลยแทบไม่ช่วยมือใหม่เลย เอกสารที่ดีต้องมีทั้งสองอย่าง

  • เห็นด้วยอย่างยิ่ง อยากเตือนผู้เขียน man page ทุกคนว่ามี section มาตรฐานชื่อ EXAMPLE อยู่ด้วย แนะนำให้อ้างอิง เอกสารทางการของ man(1)

  • ฉันไม่เคยรู้สึกว่ามีปัญหาแบบนั้นเลย ปกติฉันจะลองเขียนโค้ดไปก่อน แล้วค่อยเรียนรู้คำสั่งหรือคำศัพท์ ดู error return code สาเหตุของมัน และความหมายของพารามิเตอร์ไปทีละอย่าง ต่อให้ไม่มีตัวอย่าง ถ้าเอกสารถูกต้องครบถ้วนก็เพียงพอ ตรงกันข้าม ถ้ามีแต่ตัวอย่างโดยไม่มีคำอธิบายอะไรเลย นั่นแย่ที่สุดจริง ๆ จะมีเอกสารแบบไหนกันที่ไม่บอกด้วยซ้ำว่าพารามิเตอร์คืออะไรและหมายถึงอะไร?

  • ฉันชอบที่เมื่อก่อน Stack Overflow ก็เคยลองทำอะไรคล้าย ๆ กันในชื่อ Stack Overflow Documentation ซึ่งเปิดเบต้าอยู่ช่วงปี 2016 ถึง 2017 พยายามทำเอกสารแบบเน้นตัวอย่าง แต่สุดท้ายก็ปิดไป ถึงอย่างนั้นเนื้อหาที่ชุมชนทิ้งไว้ก็ยังเปิดเผยภายใต้ CC BY-SA อยู่

  • ลองดู cheat.sh ได้ ฉันใช้งานตรงจากสคริปต์ด้วย curl cheat.sh/"$1"

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

• ตัวอย่างไม่ได้มีประโยชน์แค่มือใหม่หรือคนที่ใช้งานเป็นครั้งคราวเท่านั้น แม้แต่ผู้ใช้ที่ชำนาญก็ยังต้องการเอกสารแบบเป็นทางการที่มีการจัดวางพารามิเตอร์ครบทั้งหมด เช่น เอกสารของ requests มักถูก Google พาไปหน้าที่เต็มไปด้วยตัวอย่างอย่าง Quickstart ซึ่งน่าหงุดหงิด ทุกคนรู้จัก HTTP GET อยู่แล้ว แต่ตัวเลือกอื่น ๆ คืออะไร การจัดการ timeout เป็นอย่างไร หรือ raise_for_status จะมองข้าม 204 หรือไม่ กลับหาคำตอบยาก ทั้งสองอย่างจำเป็น แต่ถ้าเวลาของนักพัฒนามีจำกัด ฉันจะเลือกทำเอกสารที่ถูกต้องให้ดีก่อน ลิงก์ตัวอย่าง requests Quickstart

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

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

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

  • เรามีทั้งสองอย่างพร้อมกันได้ ตัวอย่างกับเอกสารเชิงเทคนิคไม่ได้ขัดแย้งกัน

  • เรื่อง occasional users นี่แหละคือสิ่งที่ฉันกำลังพูดถึง ทุกครั้งที่ต้องสลับไปมาระหว่างโปรเจกต์ ภาษา หรือเฟรมเวิร์ก จะมีต้นทุนทางความคิดสูงมากในการกู้บริบทกลับมาและทำความเข้าใจว่าอยู่ในสถานการณ์แบบไหน

• จะพูดถึง Perl ในแง่ไหนก็ได้ แต่เอกสารของ Perl มีประโยชน์จริง ๆ เพราะขึ้นต้นด้วย section ชื่อ SYNOPSIS เสมอ ทำให้เห็นโค้ดตัวอย่างที่ใช้ได้ทันที จากนั้นค่อยตามด้วยคำอธิบาย เอกสารอ้างอิง และตัวอย่างเพิ่มเติม ดูตัวอย่างได้ที่ เอกสาร bigrat, เอกสาร Archive::Tar เวลาเขียนเอกสารโปรเจกต์ก็ควรอ้างอิงสไตล์ของ Perl และตัวสไตล์นั้นเองก็ มีการสรุปไว้อย่างดี

  • ฉันเคยใช้ Perl ช่วงต้นยุค 2000 แล้วบังเอิญกลับมาใช้อีกครั้งในปี 2014 มันให้ความรู้สึกเหมือนจำทุกอย่างกลับมาได้เอง น่าประทับใจมาก อาจเป็นเพราะมุมมองเชิงภาษาศาสตร์และท่าทีของ Larry Wall ด้วย มันไม่ได้แม่นยำแบบคณิตศาสตร์ แต่ให้ความรู้สึกเหมือน "คุยกับเพื่อน" มาก

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

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

• กรอบแนวคิด Diátaxis แสดงให้เห็นชัดว่าเอกสารมีหลายประเภทและแต่ละประเภทมีหน้าที่ต่างกัน ไม่ใช่ว่าอะไรอย่างหนึ่งคือ "ดีที่สุด" แต่สำคัญที่ใช้ให้ตรงกับความต้องการที่ต่างกัน เว็บไซต์ทางการของ Diátaxis

  • เรื่องนี้ควรอยู่ด้านบนสุดด้วยซ้ำ น่าหงุดหงิดเล็กน้อยที่ต้องเลื่อนผ่านการถกกันมากมายกว่าจะมีคนพูดถึง Diátaxis มุมมองของฉันคือ ตัวอย่างเป็นแกนสำคัญของเอกสารก็จริง แต่แทนที่จะเป็น "ประเภทเอกสาร" ในตัวเอง มันใกล้เคียงกับการเป็น "เทคนิคของเอกสาร" ที่สำคัญมากกว่า

  • ใช่เลย! ตัวอย่าง (หรือติวโทเรียล) เป็นหนึ่งในแกนของการสอนระบบ ฉันไม่แน่ใจว่าใครเป็นคนคิดขึ้นก่อน แต่ลิงก์นี้ดูคล้ายกับลิงก์ผู้เขียนท้ายบทความ: > "แม้แต่โปรเจกต์ใหญ่ ๆ ก็ไม่ค่อยมีเอกสารครบทั้ง 4 ประเภท ดังนั้นบางครั้งการกดลิงก์ ‘Documentation’ จึงน่าลังเล" ฉันชอบเอกสารเชิงอธิบาย เพราะเมื่อเข้าใจโครงสร้างหรือเหตุผลการทำงานแล้ว ก็จะรับตัวอย่างหรือติวโทเรียลได้ง่ายขึ้น ถ้ามีนักเขียนเทคนิคหรือผู้สอนฝีมือดีช่วยวางกรอบนี้ตั้งแต่ต้นก็จะมีประโยชน์มาก ส่วน API reference มักจำเป็นที่สุดตอนทำ wrapper หรือ implementation ที่เข้ากันได้ เดิมทีหลายโปรเจกต์เริ่มจากเอกสารอ้างอิง API ภายใน แล้วค่อยเปิดออกมาสู่ภายนอก ดูระบบเอกสารของ divio

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

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

  • เอกสารที่ย่ำแย่ของ Unreal ก็ทำให้ฉันเสียเวลาอย่างมหาศาลเหมือนกัน พวกเขามีบรรยากาศแบบ "โค้ดคือตัวเอกสาร" แต่คำอธิบายแบบ "ภาพหน้าจอโหนดของ Blueprint" นั้นชวนขำจริง ๆ

  • เรื่องเกี่ยวกับ £JOB ฉันสงสัยว่าตอนคนใช้ $job เขาหมายถึงงานที่ได้เงินทำจริง ๆ หรือแค่ตั้งชื่อตัวแปรตามธรรมดา แค่นี้ก็ทำให้โลกทัศน์ของฉันสั่นคลอนแล้ว

• ฉันใช้ ImageMagick บ่อย และที่ผ่านมาแทบต้องค้นหาตัวอย่างจาก Google ตลอด เลยเอาบันทึกที่จดไว้ส่วนตัวมารวมเป็นชุดตัวอย่างคำสั่งเล็ก ๆ พร้อมเติมคำอธิบายของแต่ละอาร์กิวเมนต์อย่างละเอียด ฉันคิดว่าไม่ควรมีแค่ตัวอย่างล้วน ๆ แบบในโพสต์บล็อกนี้ แต่ต้องมีคำอธิบายประกอบด้วย ตอนนี้ยังเป็นฉบับร่าง แต่สำหรับงานประจำวันอย่าง resize, optimize และ layering นั้นมีประโยชน์มากแล้ว ลิงก์เผยแพร่โน้ตของฉัน

• ตัวอย่างโค้ดสามารถรันเป็น unit test ได้ เพื่อป้องกันไม่ให้เอกสารล้าสมัยหรือพัง ซึ่งเป็นข้อดีที่ภาษาธรรมชาติทำไม่ได้

  • ตอนนี้เมื่อ LLM พัฒนาขึ้น ก็น่าจะเริ่มลองใช้มันเพื่อตรวจสอบความถูกต้องของเอกสาร API ได้เหมือนกัน

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

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

[howudoin]

สาย Java และวัฒนธรรมเชิงวัตถุมีประโยคอธิบายที่ไร้ความหมายกับเอกสารแบบพิธีรีตองเยอะเป็นพิเศษ และแม้แต่เฟรมเวิร์กฝั่ง Python ที่รับบรรยากาศนั้นต่อมาก็ยังขาดแคลนตัวอย่างอย่างเห็นได้ชัด

ตัวอย่างของการทำเอกสารที่ไร้ความหมาย
add(left, right) - บวกตัวถูกดำเนินการฝั่งซ้ายกับฝั่งขวา

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

ถ้าเป็น man page ของภาษา C แค่คำอธิบายสั้น ๆ ก็ยังพอใช้งานได้ อย่างน้อยก็เดาจากชื่อฟังก์ชันและชื่อพารามิเตอร์ได้