Kỷ luật trích dẫn

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

Tổng quan nhanh

Đây là trang mà mọi trang Insider_ khác trỏ đến khi giải thích cách nó trích dẫn một tiêu chuẩn. Trang này giải thích vì sao tài liệu diễn giải lại đặc tả thay vì trích dẫn nguyên văn, cách mỗi tuyên bố nêu rõ tiêu chuẩn và đúng điều khoản mà nó dựa vào, và một trích dẫn sạch 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 chúng với một tiêu chuẩn và điều khoản được nêu tên. Trích dẫn đó chỉ có giá trị khi kỷ luật đứ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ì trích dẫn 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ể truy ngược về nguồn của nó, mà không sao chép lại chính nguồn đó. Một trích dẫn chính xác cùng một bản diễn giải trung thực trả lời cả hai vấn đề, và trang này chính là đặc tả của chúng.

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ố nêu rõ tiêu chuẩn và đúng điều khoản; 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 nêu rõ một điều khoản hoặc mục cụ thể, không phải cả một tài liệu, để người rà soát tiếp theo có thể mở điều khoản đó ra và xác nhận phần diễn giải so với nó.
Một trích dẫn nêu rõ loại nguồn mà nó dựa vào — một điều khoản, mã của engine, một bài test, một phép đo — để một tuyên bố quá mức có thể nhận ra ngay từ cái nhìn đầu tiên.
Khi một tuyên bố không thể gắn với một điều khoản mà người viết đã thực sự đọc, nó không được làm giả. Nó được giữ lại, đánh dấu là chưa giải quyết, 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 nêu rõ tiêu chuẩn và điều khoản rồi diễn giải lại yêu cầu bằng giọng văn riêng.

Đ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ố nêu rõ điều khoản, không chỉ tài liệu

Cơ chế làm cho một bản diễn giải có thể kiểm chứng chính là sự chính xác. Mỗi tuyên bố standard-backed đều nêu rõ đúng điều khoản hoặc mục mà nó dựa vào — chẳng hạn ISO 32000-2 §6 — chứ không chỉ tài liệu. Người rà soát không phải tin vào trí nhớ của người viết; họ mở điều khoản đó ra và đối chiếu với phần diễn đạt lại. Tham chiếu điều khoản 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ó cho biết nơi cần xem mà không mang theo văn bản của nguồn.

Một trích dẫn cho biết đây là loại nguồn nào

Một trích dẫn trả lời câu hỏi “từ đâu”. Nó cũng phải trả lời câu hỏi “loại nào”. Nói rằng một tuyên bố dựa vào một điều khoản của một tiêu chuẩn là một cam kết khác với nói rằng nó dựa vào chính mã của engine, vào một bài test, hay vào một phép đo. NextPDF giữ các loại đó tách bạch để người đọc có thể cân nhắc: code và test xếp trên hành vi runtime, runtime trên metadata, và metadata trên văn bản diễn giải. Một trang editorial như trang này không tự nhận là code-backed.

Loại nguồn	Nó cam kết điều gì	Nó không cam kết điều gì
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 đó
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	Rằng mã hiện thực điều đó không có ngoại lệ
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
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
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
Nguyên tắc thiết kế	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
Editorial	Một lời giải thích có lập luận, sắp xếp tài liệu khác	Một bảo đảm hành vi mới của riêng nó
Hỗn hợp	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à editorial: nó không khẳng định bất kỳ hành vi nào của engine. Nó giải thích kỷ luật mà trích dẫn của các trang khác dựa vào. Đó là cơ sở 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ể đọc được nguồn

Việc tiếp cận một tiêu chuẩn không phải lúc nào cũng tức thì — một đặc tả được cấp phép có thể là đặc tả mà người viết còn phải tìm cách có được, hoặc một điều khoản có thể cần đọc lần thứ hai cho đến khi ý nghĩa của nó rõ ràng. Tính chính trực của kỷ luật thể hiện ở điều xảy ra khi đó. Người viết không phỏng đoán. Một tuyên bố chưa thể gắn với một điều khoản mà người viết đã thực sự đọc sẽ được giữ lại, gắn với tài liệu 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, và trang vẫn chưa được xuất bản cho đến khi điều khoản được trích dẫn đúng cách.

Những hành vi bị cấm được liệt kê rõ và có thể kiểm tra: một số điều khoản bịa ra cho có vẻ chính xác, một trích dẫn được dàn dựng như thể đã được đọc trong khi thực ra viết theo trí nhớ, hoặc âm thầm xóa tuyên bố để né việc trích dẫn. Một trích dẫn còn dang dở được đánh dấu đúng cách trên bản nháp là khoản nợ có ghi chú, 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 đó.

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 gắn một tuyên bố với điều khoản của nó.

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"

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. spec và clause 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 đó. Mục đó mang theo con trỏ tới điều khoản, không mang theo lời văn của điều khoản.

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 điều khoả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 tài liệu 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ó dựa vào loại nguồn nào trước khi bạn quyết định đặt bao nhiêu trọng số cho nó.

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 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 và 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 trích dẫn 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 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 dựa vào cơ sở đó thay vì cơ sở 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, nêu rõ đúng điều khoản, 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.
Tham chiếu điều khoản — đúng điều khoản hoặc mục mà một bản diễn giải dựa vào, được ghi lại để người rà soát có thể mở ra và xác minh phần diễn đạt lại.
Tuyên bố standard-backed — một 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 của một tiêu chuẩn được nêu tên, khác với tuyên bố dựa vào mã của engine, một bài test, một phép đo, hay lập luận biên tập.
Trích dẫn chưa giải quyết — một tuyên bố chưa thể gắn với một điều khoản mà người viết đã đọc; được giữ lại, đánh dấu là còn dang dở, và không được xuất bản thay vì bị làm giả.