วินัยการอ้างอิง

Spec: ISO/IEC/IEEE 26514 Spec: ISO 24495-1 Evidence: Editorial

โดยสรุป

นี่คือหน้าที่หน้าอื่น ๆ ใน Insider_ อ้างถึงเมื่อกล่าวถึง “evidence level” หน้านี้อธิบายว่าทำไมเอกสารเหล่านี้จึงถอดความมาตรฐานแทนการอ้างคำต่อคำ ข้อกล่าวอ้างผูกกับ reference ID ที่ตรวจสอบซ้ำได้อย่างไร และหลักฐานทั้งแปดระดับให้คำมั่นและไม่ให้คำมั่นในสิ่งใด

หน้านี้เขียนขึ้นสำหรับวิศวกรอาวุโสที่ต้องการทราบกฎเกณฑ์เบื้องหลังข้อกล่าวอ้างก่อนจะเชื่อถือข้อกล่าวอ้างนั้น และความต้องการนี้สมเหตุสมผล

ทำไมเรื่องนี้จึงสำคัญ

หน้า Insider_ อื่นทุกหน้าตั้งข้อกล่าวอ้างและติดป้าย evidence level ป้ายนั้นมีค่าก็ต่อเมื่อระบบที่อยู่เบื้องหลังชัดเจน หาก “standard-backed” อาจหมายความได้ตั้งแต่ “อ่านสเปกอย่างละเอียด” ไปจนถึง “จำได้คร่าว ๆ ว่ามีเนื้อหาอะไร” ป้ายนั้นก็เป็นเพียงเครื่องประดับ

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

ฉบับย่อ

Insider_ ถอดความมาตรฐานและไม่อ้างคำต่อคำจากมาตรฐานที่มีลิขสิทธิ์ ข้อกล่าวอ้างจะอ้างถึงมาตรฐาน ข้อกำหนด และ reference ID โดยไม่ทำซ้ำถ้อยคำของมาตรฐาน
การถอดความไม่ใช่ทางเลี่ยง แต่เป็น การทดสอบความเข้าใจ การเรียบเรียงข้อกำหนดใหม่ด้วยสำนวนของ NextPDF เองบังคับให้ผู้เขียนต้องเข้าใจข้อกำหนดนั้น และทำให้คำศัพท์สอดคล้องกับอภิธานศัพท์ Spec: ISO/IEC/IEEE 26514, §8
ทุกข้อกล่าวอ้างที่อิงมาตรฐานจะมี reference_id ยาว 64 อักขระ อยู่ใน front-matter citations ของหน้า เพื่อให้ผู้ตรวจทานรายถัดไปสามารถดึงช่วงแหล่งที่มาเดิมกลับมาและยืนยันการถอดความได้
ป้ายระบุ evidence level หนึ่งในแปดประเภท ซึ่งบอก ชนิด ของหลักฐาน เพื่อให้การกล่าวอ้างเกินจริงมองเห็นได้ทันที
เมื่อไม่สามารถดึงแหล่งที่มาได้ ข้อกล่าวอ้างจะ ไม่ถูกแต่งขึ้น แต่จะถูกเก็บไว้ ทำเครื่องหมายว่ายังไม่ได้แก้ไขเทียบกับสมุดบัญชี re-pin และหน้านั้นจะยังไม่เผยแพร่ ซึ่งเป็นโปรโตคอลที่มีการบันทึกไว้ ไม่ใช่การด้นสด

NextPDF ดำเนินการเรื่องนี้อย่างไร

ถอดความ ไม่ใช่อ้างคำต่อคำ

กฎที่เข้มงวดที่สุดในลำดับชั้นสไตล์ของ NextPDF ซึ่งมีผลเหนือกว่าคู่มือต้นทางทุกฉบับ คือห้ามนำเนื้อหาคำต่อคำจากหน่วยงานมาตรฐานที่มีลิขสิทธิ์มาใช้ ไม่ว่าข้อความที่คัดมาจะสั้นเพียงใด แต่ละหน้าจะอ้างถึงมาตรฐานและข้อกำหนด ถอดความข้อกำหนดด้วยสำนวนของตนเอง และบันทึก reference ID ของแหล่งที่มาแทน

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

ภาษาเรียบง่ายตัดสินจากว่าผู้อ่านสามารถค้นหา เข้าใจ และใช้เนื้อหาได้หรือไม่ ไม่ใช่จากว่าถ้อยคำสะท้อนแหล่งที่มา Spec: ISO 24495-1, §Introduction หรือไม่ การถอดความรับใช้เป้าหมายนั้น การอ้างคำต่อคำไม่

ข้อกล่าวอ้างผูกกับ reference ID ไม่ใช่ความทรงจำ

กลไกที่ทำให้การถอดความตรวจสอบได้คือ reference ID ทุกข้อกล่าวอ้างที่อิงมาตรฐานจะมี reference_id เต็มความยาว 64 อักขระอยู่ใน front-matter citations ของหน้า ซึ่งระบุช่วงแหล่งที่มาที่ใช้ถอดความอย่างแม่นยำ ผู้ตรวจทานไม่ต้องเชื่อความทรงจำของผู้เขียน แต่สามารถดึงช่วงนั้นกลับมาเปรียบเทียบได้ reference ID คือจุดเชื่อมระหว่างแหล่งที่มาที่อ้างคำต่อคำไม่ได้กับข้อกล่าวอ้างที่ตรวจสอบได้ reference ID นำ ตำแหน่งของหลักฐาน มาด้วยโดยไม่นำเนื้อหาของหลักฐานมาด้วย

evidence level บอกว่านี่เป็นหลักฐานชนิดใด

การอ้างอิงตอบคำถามว่า “มาจากไหน” evidence level ตอบคำถามว่า “เป็นหลักฐานชนิดใด” หน้า Insider_ ทุกหน้าระบุ evidence level หนึ่งระดับ แสดงในแถวป้าย และเลือกจากชุดที่กำหนดไว้แน่นอนแปดประเภท ลำดับความน่าเชื่อถือจัดให้โค้ดและการทดสอบอยู่เหนือ runtime, runtime อยู่เหนือ metadata และ metadata อยู่เหนือเนื้อความ หน้าเชิงบรรณาธิการจะไม่แสร้งว่าเป็นหน้าที่อิงโค้ด

ระดับหลักฐาน (Evidence level)	สิ่งที่ให้คำมั่น	สิ่งที่ ไม่ ให้คำมั่น
Evidence: Code-backed	ข้อกล่าวอ้างถูกตรวจสอบเทียบกับซอร์สโค้ดของเอนจินหรือตัวอย่างที่รันได้	ว่ามาตรฐานกำหนดให้ทำเช่นนั้น
Evidence: Standard-backed	ข้อกล่าวอ้างยึดโยงกับข้อกำหนดที่อ้างอิงและถอดความ พร้อม reference ID	ว่าโค้ดปัจจุบันนำไปใช้โดยไม่มีข้อยกเว้น
Evidence: Test-backed	การทดสอบในชุดทดสอบยึดพฤติกรรมไว้ให้คงที่	ตัวเลขด้านสมรรถนะ
Evidence: Benchmark-backed	การวัดภายใต้วิธีที่ระบุไว้รองรับตัวเลขนั้น	ตัวเลขเดียวกันบนฮาร์ดแวร์ของคุณ
Evidence: Artifact-backed	อาร์ติแฟกต์ที่ผลิตขึ้น (ผลลัพธ์ของการ build หรือรายงาน) แสดงให้เห็นข้อกล่าวอ้างนั้น	การกำหนดของมาตรฐาน
Evidence: Design principle	การตัดสินใจด้านการออกแบบที่จงใจและมีเหตุผลรองรับ	การวัดเชิงประจักษ์
Evidence: Editorial	คำอธิบายที่มีเหตุผลซึ่งจัดระเบียบหลักฐานอื่น	การรับประกันพฤติกรรมใหม่ในตัวเอง
Evidence: Mixed evidence	หน้าผสมหลักฐานหลายฐานและระบุว่าเป็นฐานใดในแต่ละข้อกล่าวอ้าง	ฐานเดียวที่ชัดเจน

หน้านี้เป็น Evidence: Editorial ไม่ยืนยันพฤติกรรมของเอนจินใดในตัวเอง หน้านี้อธิบายระบบที่ป้ายของหน้าอื่นอาศัยอยู่ นั่นคือระดับที่ซื่อตรงสำหรับหน้านี้ และการระบุเช่นนั้นคือการนำวินัยมาใช้กับตัวเอง

เมื่อไม่สามารถดึงแหล่งที่มาได้

การดึงแหล่งที่มาอาจไม่พร้อมใช้งานเสมอไป ความซื่อตรงของวินัยนี้แสดงออกในสิ่งที่เกิดขึ้นเมื่อนั้น คิว การจำกัดอัตรา หรือการหยุดพักเรื่องงบประมาณตามปกติ ไม่ใช่ การขัดข้อง ผู้เขียนต้องรอ การขัดข้องจริงจะกระตุ้นการสำรองที่มีการบันทึกไว้ คือข้อกล่าวอ้างจะถูก เก็บไว้ แนบกับหลักฐานในรีโพและการอ้างอิงมาตรฐานที่โค้ดประกาศไว้เอง ทำเครื่องหมายอย่างชัดเจนว่ายังไม่ได้แก้ไข เทียบกับสมุดบัญชี re-pin ที่ใช้เป็นฐาน และหน้านั้น จะยังไม่เผยแพร่ จนกว่าจะปักหมุด reference ID ได้จริง

การกระทำต้องห้ามถูกแจกแจงและตรวจสอบได้ ได้แก่ reference ID ที่กุขึ้น ค่าที่เติมอักขระหรือเติมคำนำหน้าให้ดูเหมือนจริง ข้อกำหนดที่เขียนจากความทรงจำแล้วแต่งให้ดูเหมือนการอ้างอิงที่ดึงมา หรือการลบข้อกล่าวอ้างอย่างเงียบ ๆ เพื่อหลบเลี่ยงการอ้างอิง การขัดข้องที่ทำเครื่องหมายไว้อย่างถูกต้องบนฉบับร่างคือ หนี้ที่ลงรายการไว้ในสมุดบัญชี ไม่ใช่ข้อบกพร่อง การตรวจสอบแบบออฟไลน์ที่ให้ผลแน่นอนบังคับใช้ความแตกต่างนี้อย่างชัดเจน

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

หลักฐานบอกอะไร

หน้านี้เป็น Evidence: Editorial ดังนั้นฐานของหน้านี้คือการกำกับดูแลเอกสารในรีโพนี้ร่วมกับมาตรฐานที่รองรับวินัยดังกล่าว ข้อกล่าวอ้างในหน้านี้ตรวจสอบได้สองทาง คือด้วยการอ่านกฎในรีโพ และด้วยการดึงข้อกำหนดที่อ้างอิงกลับมาใหม่

ข้อกล่าวอ้าง	ฐาน	จุดยึด
การถอดความบังคับให้ต้องเข้าใจ	มาตรฐาน	ภาษาเรียบง่ายตัดสินจากการใช้งานของผู้อ่าน ไม่ใช่การสะท้อนแหล่งที่มา Spec: ISO 24495-1, §Introduction
คำศัพท์คงความสอดคล้อง	มาตรฐาน	คำศัพท์แต่ละคำใช้อย่างสอดคล้องตลอดทั้งเอกสาร Spec: ISO/IEC/IEEE 26514, §8
การตรวจทานเป็นส่วนหนึ่งของกระบวนการ	มาตรฐาน	การตรวจสอบยืนยันและการทดสอบยืนยันความใช้ได้ภายในการพัฒนา Spec: ISO/IEC/IEEE 26513, §Foreword
evidence level จดจำได้เป็นอันดับแรก	มาตรฐาน	ใช้การจดจำแทนการระลึก Spec: ISO 9241-110, §5.6.2
ไม่มีเนื้อหาที่มีลิขสิทธิ์แบบคำต่อคำ และปักหมุดด้วยการอ้างอิง	ในรีโพ	`docs/style/nextpdf-overrides.md` §5; `composer docs:jaccard-fingerprint`
การสำรองเมื่อขัดข้องเป็นโปรโตคอลจริง	ในรีโพ	การกำกับดูแลการสำรอง RAG ตามบรรทัดฐาน ร่วมกับเกต `docs:rag-fallback-check` แบบออฟไลน์

ตัวอย่างเชิงปฏิบัติ

วินัยนี้จับต้องได้ในรูปของโครงสร้าง front-matter citations ของหน้า แต่ละรายการคือใบเสร็จของข้อกล่าวอ้าง

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # full 64-char reference ID — the join to the source span, re-verifiable
    reference_id: "<64-hex digest>"
    # NextPDF-worded topic — the paraphrase, never the standard's text
    topic: "A writer's created or amended PDF elements must conform and stay consistent"

ตั้งใจให้ไม่มีฟิลด์ quote topic คือการเรียบเรียงใหม่ของ NextPDF เอง reference_id คือวิธีให้ผู้ตรวจทานกลับไปยังแหล่งที่มาที่แม่นยำเพื่อตรวจสอบการเรียบเรียงใหม่นั้น ใบเสร็จนำ ตัวชี้ ไปยังหลักฐาน ไม่ใช่ถ้อยคำของหลักฐาน

ความเข้าใจผิดที่พบบ่อย

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

กับดักที่สองคือการมองว่า “editorial” เป็นเกรดที่อ่อนกว่า “standard-backed” ไม่ใช่เกรดเลย แต่เป็น ชนิด ที่ต่างกัน หน้าเชิงบรรณาธิการเช่นหน้านี้จัดระเบียบและอธิบายหลักฐานอื่น หน้านี้ติดป้ายอย่างถูกต้อง และป้ายนั้นเองคือประเด็น ระบบทำงานได้เพราะหน้าบอกคุณว่ากำลังเสนอหลักฐานชนิดใดก่อนที่คุณจะตัดสินว่าจะให้น้ำหนักเพียงใด

ข้อจำกัดและขอบเขต

หน้านี้กำหนด วินัย การอ้างอิง ไม่ใช่สไตล์ชีต การกำกับดูแลการสำรอง หรือโค้ดของเกต อาร์ติแฟกต์ที่เป็นแหล่งอ้างอิงอยู่ในรีโพ (docs/style/nextpdf-overrides.md §5 การกำกับดูแลการสำรอง RAG ตามบรรทัดฐาน และสคริปต์ composer.jsondocs:*) และมีลำดับเหนือกว่าสรุปใด ๆ ในหน้านี้หากมีความขัดแย้งกัน หน้านี้ไม่ยืนยันพฤติกรรมของเอนจินใด

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

เอกสารที่เกี่ยวข้อง

Documentation as a product วินัยคุณภาพที่กว้างกว่าซึ่งระบบการอ้างอิงนี้เป็นส่วนหนึ่ง
The standards landscape มาตรฐานที่การอ้างอิงเหล่านี้ชี้ไป และข้อกำหนดกลายเป็นพฤติกรรมที่บันทึกไว้ได้อย่างไร
The NextPDF testing pyramid หลักฐานที่อิงการทดสอบหมายความว่าอย่างไรเมื่อหน้าหนึ่งประกาศระดับนั้นแทนที่จะเป็นระดับนี้

อภิธานศัพท์

วินัยการอ้างอิง (Citation discipline) ชุดกฎที่กำกับว่าข้อกล่าวอ้างของ Insider_ ผูกกับแหล่งที่มาอย่างไร คือถอดความ อ้างถึงข้อกำหนด ปักหมุด reference ID และไม่อ้างคำต่อคำจากมาตรฐานที่มีลิขสิทธิ์
การถอดความ (Paraphrase) การเรียบเรียงข้อกำหนดใหม่ด้วยสำนวนของ NextPDF เองที่สอดคล้องกับอภิธานศัพท์ คือการทดสอบความเข้าใจที่ใช้แทนการอ้างคำต่อคำ
reference_id ตัวชี้ความครบถ้วนสมบูรณ์เต็มความยาว 64 อักขระสำหรับช่วงแหล่งที่มาที่แม่นยำซึ่งใช้ถอดความ บันทึกไว้เพื่อให้ผู้ตรวจทานสามารถดึงกลับมาและตรวจสอบได้
Evidence level ชนิด ของหลักฐานที่ประกาศไว้เบื้องหลังข้อกล่าวอ้างของหน้า หนึ่งในแปดประเภท (code-, standard-, test-, benchmark-, artifact-backed, design-principle, editorial, mixed) แสดงในแถวป้าย
การอ้างอิงที่ยังไม่ได้แก้ไข (Unresolved citation) ข้อกล่าวอ้างที่ไม่สามารถปักหมุด reference ID ได้เนื่องจากการขัดข้องในการดึงข้อมูลจริง ถูกเก็บไว้ ทำเครื่องหมายเทียบกับสมุดบัญชี re-pin และระงับจากการเผยแพร่แทนการแต่งขึ้น