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

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

โดยสรุป

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

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

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

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

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

ฉบับย่อ

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

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

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

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

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

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

ข้อกล่าวอ้างระบุข้อกำหนด ไม่ใช่เพียงเอกสาร

กลไกที่ทำให้การถอดความตรวจสอบได้คือความแม่นยำ ทุกข้อกล่าวอ้างที่อิงมาตรฐานจะระบุข้อกำหนดหรือหัวข้อที่แม่นยำซึ่งมันอ้างอิงอยู่ เช่น ISO 32000-2 §6 ไม่ใช่เพียงเอกสาร ผู้ตรวจทานไม่ต้องเชื่อความทรงจำของผู้เขียน แต่สามารถเปิดข้อกำหนดนั้นและเปรียบเทียบกับการเรียบเรียงใหม่ได้ การอ้างอิงถึงข้อกำหนดคือจุดเชื่อมระหว่างแหล่งที่มาที่อ้างคำต่อคำไม่ได้กับข้อกล่าวอ้างที่ตรวจสอบได้ มันบอก ว่าควรดูที่ใด โดยไม่นำเนื้อหาของแหล่งที่มามาด้วย

การอ้างอิงบอกว่านี่เป็นแหล่งที่มาชนิดใด

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

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

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

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

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

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

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

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

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

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # 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 เอง spec และ clause คือวิธีให้ผู้ตรวจทานกลับไปยังแหล่งที่มาที่แม่นยำเพื่อตรวจสอบการเรียบเรียงใหม่นั้น รายการนำ ตัวชี้ ไปยังข้อกำหนด ไม่ใช่ถ้อยคำของข้อกำหนด

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

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

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

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

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

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

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

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

อภิธานศัพท์

วินัยการอ้างอิง (Citation discipline) ชุดกฎที่กำกับว่าข้อกล่าวอ้างของ Insider_ ผูกกับแหล่งที่มาอย่างไร คือถอดความ ระบุข้อกำหนดที่แม่นยำ และไม่อ้างคำต่อคำจากมาตรฐานที่มีลิขสิทธิ์
การถอดความ (Paraphrase) การเรียบเรียงข้อกำหนดใหม่ด้วยสำนวนของ NextPDF เองที่สอดคล้องกับอภิธานศัพท์ คือการทดสอบความเข้าใจที่ใช้แทนการอ้างคำต่อคำ
การอ้างอิงถึงข้อกำหนด (Clause reference) ข้อกำหนดหรือหัวข้อที่แม่นยำซึ่งการถอดความอ้างอิงอยู่ บันทึกไว้เพื่อให้ผู้ตรวจทานสามารถเปิดมันและตรวจสอบการเรียบเรียงใหม่ได้
ข้อกล่าวอ้างที่อิงมาตรฐาน (Standard-backed claim) ข้อกล่าวอ้างที่ยึดโยงกับข้อกำหนดที่อ้างอิงและถอดความของมาตรฐานที่ระบุชื่อ แตกต่างจากข้อกล่าวอ้างที่อิงโค้ดของเอนจิน การทดสอบ การวัด หรือการให้เหตุผลเชิงบรรณาธิการ
การอ้างอิงที่ยังไม่ได้แก้ไข (Unresolved citation) ข้อกล่าวอ้างที่ยังผูกกับข้อกำหนดที่ผู้เขียนอ่านแล้วไม่ได้ ถูกเก็บไว้ ทำเครื่องหมายว่ายังเปิดค้าง และระงับจากการเผยแพร่แทนการแต่งขึ้น