Kỷ luật trích dẫn

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

Tổng quan nhanh

Đây là trang mà mọi trang Insider_ khác trỏ đến khi nói về “mức bằng chứng”. Trang này giải thích vì sao tài liệu diễn giải lại tiêu chuẩn thay vì trích dẫn nguyên văn, cách mỗi tuyên bố gắn với một reference ID để bạn có thể xác minh lại, và mỗi mức trong số tám mức bằng chứng cam kết cũng như không cam kết điều gì.

Trang này được viết cho kỹ sư cấp cao: người muốn biết những quy tắc nào đã được dùng để đưa ra một tuyên bố trước khi tin vào tuyên bố đó — và yêu cầu đó là hoàn toàn chính đáng.

Vì sao điều này quan trọng

Mọi trang Insider_ khác đều đưa ra tuyên bố và gắn cho chúng một mức bằng chứng. Dấu chỉ mức đó chỉ có giá trị khi hệ thống đứng sau nó rõ ràng. Nếu “standard-backed” có thể mang bất kỳ ý nghĩa nào, từ “tôi đã đọc kỹ đặc tả” cho đến “tôi nhớ đại khái nó nói gì”, thì huy hiệu chỉ còn là vật trang trí.

Còn có một ràng buộc khó hơn nữa. Nhiều tài liệu mà NextPDF phải tuân theo — các đặc tả ISO, ETSI và các tài liệu tương tự — đều được cấp phép. Việc sao chép lại văn bản của chúng, dù dài hay ngắn, đều không được phép. Vì vậy, kỷ luật này phải giải quyết hai vấn đề cùng lúc: làm cho một tuyên bố có thể kiểm chứng được so với nguồn của nó, mà không sao chép lại chính nguồn đó. Cùng một cơ chế giải quyết cả hai vấn đề, và trang này chính là đặc tả của cơ chế đó.

Phiên bản ngắn gọn

Insider_ diễn giải lại tiêu chuẩn và không bao giờ trích dẫn nguyên văn những tiêu chuẩn được cấp phép. Một tuyên bố trích dẫn tiêu chuẩn, điều khoản và một reference ID; nó không sao chép lại lời văn của tiêu chuẩn.
Diễn giải lại không phải là cách lách; đó là một bài kiểm tra mức độ hiểu. Diễn đạt lại một yêu cầu bằng chính giọng văn của NextPDF buộc người viết phải hiểu yêu cầu đó, đồng thời giữ thuật ngữ nhất quán với bảng thuật ngữ Spec: ISO/IEC/IEEE 26514, §8 .
Mỗi tuyên bố standard-backed đều mang một reference_id 64 ký tự trong phần front-matter citations của trang, để người rà soát tiếp theo có thể truy xuất lại đúng đoạn nguồn và xác nhận phần diễn giải.
Huy hiệu công bố một mức bằng chứng — một trong tám loại — cho biết loại chứng cứ, để một tuyên bố quá mức có thể nhận ra ngay từ cái nhìn đầu tiên.
Khi không thể truy xuất được nguồn, tuyên bố không được làm giả. Nó được giữ lại, đánh dấu là chưa giải quyết trong một sổ ghi các mục chờ ghim lại, và trang vẫn chưa được xuất bản — một quy trình đã được ghi thành tài liệu, không phải làm tùy hứng.

Cách NextPDF tiếp cận vấn đề này

Diễn giải lại, không trích dẫn nguyên văn

Quy tắc nghiêm ngặt nhất trong hệ phân cấp văn phong của NextPDF ghi đè mọi hướng dẫn ở cấp trên: không sao chép nguyên văn từ một tổ chức tiêu chuẩn được cấp phép, bất kể đoạn trích ngắn đến đâu. Thay vào đó, một trang trích dẫn tiêu chuẩn và điều khoản, diễn giải lại yêu cầu bằng giọng văn riêng, rồi ghi lại reference ID của nguồn.

Điều này thường được xem là một ràng buộc về cấp phép, và đúng là như vậy. Nhìn từ góc độ biên tập còn hữu ích hơn. Một trích dẫn nguyên văn chỉ chứng tỏ rằng bạn biết sao chép. Một bản diễn giải trung thực cho thấy bạn đã hiểu điều khoản đủ rõ để diễn đạt lại mà không làm thay đổi ý nghĩa của nó. Nó cũng giúp câu văn giữ nguyên vốn từ vựng nhất quán của NextPDF thay vì đổi giọng giữa chừng, điều mà mô hình chất lượng tài liệu yêu cầu Spec: ISO/IEC/IEEE 26514, §8 . Ngôn ngữ rõ ràng được đánh giá qua việc người đọc có thể tìm, hiểu và sử dụng nội dung hay không, chứ không phải qua việc câu chữ có phản ánh đúng nguồn hay không Spec: ISO 24495-1, §Introduction ; diễn giải lại phục vụ mục tiêu đó, còn trích dẫn nguyên văn thì không.

Một tuyên bố gắn với một reference ID, không gắn với trí nhớ

Cơ chế làm cho một bản diễn giải có thể kiểm chứng chính là reference ID. Mỗi tuyên bố standard-backed đều mang một reference_id đầy đủ 64 ký tự trong phần front-matter citations của trang, xác định đúng đoạn nguồn mà bản diễn giải được lấy từ đó. Người rà soát không phải tin vào trí nhớ của người viết; họ truy xuất lại đoạn đó và đối chiếu. Reference ID là điểm nối giữa một nguồn không thể trích dẫn và một tuyên bố có thể kiểm chứng. Nó mang theo thông tin chứng cứ ở đâu mà không mang theo nội dung của chứng cứ.

Mức bằng chứng cho biết đây là loại chứng cứ nào

Một trích dẫn trả lời câu hỏi “từ đâu”. Mức bằng chứng trả lời câu hỏi “loại nào”. Mỗi trang Insider_ đều công bố một mức, hiển thị trong hàng huy hiệu, lấy từ một tập cố định gồm tám mức. Thứ tự mức độ tin cậy đặt code và test cao hơn runtime, runtime cao hơn metadata, và metadata cao hơn văn bản diễn giải; một trang editorial không tự nhận là code-backed.

Mức bằng chứng	Nó cam kết điều gì	Nó không cam kết điều gì
Evidence: Code-backed	Tuyên bố được đối chiếu với mã nguồn của engine hoặc một ví dụ có thể chạy được	Rằng một tiêu chuẩn bắt buộc điều đó
Evidence: Standard-backed	Tuyên bố được neo vào một điều khoản đã được trích dẫn và diễn giải lại, kèm theo một reference ID	Rằng mã hiện thực điều đó không có ngoại lệ
Evidence: Test-backed	Một bài test trong bộ kiểm thử giữ hành vi không đổi	Một con số về hiệu năng
Evidence: Benchmark-backed	Một phép đo theo một phương pháp đã nêu rõ hỗ trợ cho con số đó	Cùng con số đó trên phần cứng của bạn
Evidence: Artifact-backed	Một sản phẩm được tạo ra (một kết quả build, một báo cáo) chứng minh điều đó	Một yêu cầu bắt buộc của tiêu chuẩn
Evidence: Design principle	Một quyết định thiết kế có chủ đích, có lập luận	Một phép đo thực nghiệm
Evidence: Editorial	Một lời giải thích có lập luận, sắp xếp các bằng chứng khác	Một bảo đảm hành vi mới của riêng nó
Evidence: Mixed evidence	Trang kết hợp nhiều cơ sở và nêu rõ cơ sở nào cho từng tuyên bố	Một cơ sở duy nhất, rõ ràng

Trang này là Evidence: Editorial : nó không khẳng định bất kỳ hành vi nào của engine. Nó giải thích hệ thống mà huy hiệu của các trang khác dựa vào. Đó là mức trung thực dành cho trang này, và việc nói rõ như vậy chính là cách kỷ luật tự áp dụng cho chính nó.

Khi không thể truy xuất được nguồn

Việc truy xuất không phải lúc nào cũng khả dụng. Tính chính trực của kỷ luật thể hiện ở điều xảy ra khi đó. Một hàng đợi bình thường, một giới hạn tốc độ, hay một lần tạm dừng theo ngân sách không phải là sự cố ngừng hoạt động. Người viết phải chờ. Một sự cố ngừng hoạt động thực sự sẽ kích hoạt một phương án dự phòng đã được ghi thành tài liệu: tuyên bố được giữ lại, gắn với bằng chứng trong repo và phần tham chiếu tiêu chuẩn do chính mã khai báo, được đánh dấu rõ ràng là chưa giải quyết trong một sổ ghi thường trực các mục chờ ghim lại, và trang vẫn chưa được xuất bản cho đến khi reference ID thực sự được ghim.

Những hành vi bị cấm được liệt kê rõ và có thể kiểm tra: một reference ID bịa đặt, một giá trị được đệm thêm hoặc thêm tiền tố để trông giống thật, một điều khoản viết theo trí nhớ rồi ngụy trang thành trích dẫn đã truy xuất, hoặc âm thầm xóa tuyên bố để né việc trích dẫn. Một sự cố ngừng hoạt động được đánh dấu đúng cách trên bản nháp là khoản nợ có ghi sổ, không phải một lỗi. Một kiểm tra ngoại tuyến có tính xác định thực thi đúng sự phân biệt đó.

Bằng chứng nói lên điều gì

Trang này là Evidence: Editorial , nên cơ sở của nó là phần quản trị tài liệu trong repository này, cùng với các tiêu chuẩn biện minh cho kỷ luật. Các tuyên bố ở đây có thể kiểm chứng theo hai cách: đọc các quy tắc trong repo, và truy xuất lại các điều khoản đã được trích dẫn.

Tuyên bố	Cơ sở	Mỏ neo
Diễn giải lại buộc người viết phải hiểu	Tiêu chuẩn	Ngôn ngữ rõ ràng được đánh giá qua cách người đọc sử dụng, không phải qua việc phản ánh đúng nguồn Spec: ISO 24495-1, §Introduction
Thuật ngữ giữ được nhất quán	Tiêu chuẩn	Mỗi thuật ngữ được dùng nhất quán xuyên suốt Spec: ISO/IEC/IEEE 26514, §8
Rà soát là một phần của quy trình	Tiêu chuẩn	Kiểm thử xác minh và xác nhận bên trong quá trình phát triển Spec: ISO/IEC/IEEE 26513, §Foreword
Mức bằng chứng được nhận ra trước tiên	Tiêu chuẩn	Ưu tiên nhận biết hơn ghi nhớ Spec: ISO 9241-110, §5.6.2
Không có văn bản được cấp phép nguyên văn; được ghim bằng tham chiếu	Trong repo	`docs/style/nextpdf-overrides.md` §5; `composer docs:jaccard-fingerprint`
Phương án dự phòng khi ngừng hoạt động là một quy trình thực sự	Trong repo	Phần quản trị dự phòng RAG mang tính quy phạm + cổng kiểm tra `docs:rag-fallback-check` ngoại tuyến

Ví dụ thực tế

Kỷ luật này rất cụ thể: nó chính là cấu trúc của phần front-matter citations của một trang. Mỗi mục là biên nhận cho một tuyên bố.

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"

Không có trường quote; đó là chủ đích thiết kế. topic là phần diễn đạt lại của chính NextPDF. reference_id là cách người rà soát quay lại đúng nguồn nhằm kiểm tra phần diễn đạt lại đó. Biên nhận mang theo con trỏ tới chứng cứ, không mang theo lời văn của chứng cứ.

Hiểu lầm phổ biến

Cái bẫy là hiểu “diễn giải lại, đừng trích dẫn” như một cách né cam kết — nói cho có vẻ uy tín mà không phải chịu trách nhiệm. Thực ra thì ngược lại. Một trích dẫn nguyên văn chẳng cam kết gì; nó mượn lời của người khác. Một bản diễn giải có trích dẫn buộc người viết phải chịu trách nhiệm về một cách diễn đạt lại mà người rà soát có thể đối chiếu với nguồn để bác bỏ. Kỷ luật này khiến các tuyên bố có trách nhiệm giải trình cao hơn, chứ không thấp hơn.

Cái bẫy thứ hai là coi “editorial” như một cấp độ yếu hơn của “standard-backed”. Nó hoàn toàn không phải là một cấp độ; nó là một loại khác. Một trang editorial như trang này sắp xếp và giải thích các bằng chứng khác. Nó được gắn nhãn đúng. Và chính cái nhãn đó mới là điều cốt lõi: hệ thống hoạt động được vì một trang cho bạn biết nó đang đưa ra loại chứng cứ nào trước khi bạn quyết định đặt bao nhiêu trọng số cho chứng cứ đó.

Giới hạn và ranh giới

Trang này đặc tả kỷ luật trích dẫn; nó không phải là hướng dẫn văn phong, phần quản trị dự phòng, hay mã của cổng kiểm tra. Các sản phẩm có thẩm quyền nằm trong repo (docs/style/nextpdf-overrides.md §5, phần quản trị dự phòng RAG mang tính quy phạm, các script composer.jsondocs:*) và sẽ được ưu tiên hơn mọi bản tóm tắt ở đây nếu chúng có sự khác biệt. Nó không khẳng định bất kỳ hành vi nào của engine.

Kỷ luật này ràng buộc tuyên bố, không ràng buộc kết luận của người đọc. Một bản diễn giải được trích dẫn trung thực cho bạn biết một điều khoản yêu cầu điều gì. Liệu cách hiểu của NextPDF có đúng với nghĩa vụ của bạn hay không vẫn là quyết định của bạn, và đó là lý do các trang về hành vi còn mang theo bằng chứng code-backed hoặc test-backed, chứ không chỉ standard-backed. Việc thực thi chỉ là một phần, và trang thừa nhận điều đó một cách trung thực: kiểm tra dự phòng ngoại tuyến đang hoạt động, còn các bộ kiểm tra trích dẫn nguyên văn và trích dẫn trực tiếp đã được tích hợp nhưng các lần chạy đầy đủ vẫn đang được hoàn thiện — được nêu là đang tiến hành, không phải đã xong.

Tài liệu liên quan

Tài liệu như một sản phẩm — kỷ luật chất lượng rộng hơn mà hệ thống trích dẫn này là một phần.
Bức tranh toàn cảnh về tiêu chuẩn — các tiêu chuẩn mà những trích dẫn này trỏ tới, và cách một điều khoản trở thành hành vi được tài liệu hóa.
Tháp kiểm thử của NextPDF — bằng chứng test-backed nghĩa là gì khi một trang công bố mức đó thay vì mức này.

Bảng thuật ngữ

Kỷ luật trích dẫn — bộ quy tắc chi phối cách một tuyên bố Insider_ gắn với nguồn: diễn giải lại, trích dẫn điều khoản, ghim một reference ID, không bao giờ trích dẫn nguyên văn một tiêu chuẩn được cấp phép.
Diễn giải lại — sự diễn đạt lại một yêu cầu bằng chính giọng văn của NextPDF, nhất quán với bảng thuật ngữ; bài kiểm tra mức độ hiểu thay cho việc trích dẫn nguyên văn.
reference_id — con trỏ toàn vẹn đủ 64 ký tự cho đúng đoạn nguồn mà một bản diễn giải được lấy từ đó, được ghi lại để người rà soát có thể truy xuất lại và xác minh.
Mức bằng chứng — loại chứng cứ được công bố đứng sau các tuyên bố của một trang, một trong tám loại (code-, standard-, test-, benchmark-, artifact-backed, design-principle, editorial, mixed), hiển thị trong hàng huy hiệu.
Trích dẫn chưa giải quyết — một tuyên bố mà reference ID không thể ghim được do một sự cố truy xuất thực sự; tuyên bố được giữ lại, đánh dấu trong sổ ghi các mục chờ ghim lại, và không được xuất bản thay vì bị làm giả.