Tài liệu như một sản phẩm

Spec: ISO/IEC/IEEE 26514 Spec: ISO/IEC/IEEE 26513 Spec: ISO 24495-1 Evidence: Standard-backed

Tổng quan nhanh

Những trang này được xây dựng theo mô hình chất lượng tài liệu, viết dựa trên một chuẩn nền về ngôn ngữ giản dị và một hệ thống phân cấp văn phong nhiều lớp, rồi được kiểm tra bằng đúng loại cổng tự động đang chạy trên mã nguồn của engine. Trang này giải thích tính kỷ luật đó và lý do NextPDF xem lỗi tài liệu là lỗi kỹ thuật.

Trang này được viết cho một kỹ sư cấp cao từng chịu hậu quả từ những tài liệu nghe có vẻ chắc chắn nhưng không thể kiểm chứng, và muốn biết điều gì khiến những tài liệu này khác đi trước khi tin vào chúng.

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

Một thư viện xử lý tài liệu được mua dựa trên niềm tin, và tài liệu chính là nơi niềm tin đó được củng cố hoặc bị rút lại. Một trang sai mà bạn không thể phát hiện còn tệ hơn việc không có trang nào. Nó biến sự thận trọng của bạn thành niềm tin đặt sai chỗ. Sự cố lộ ra trong môi trường sản xuất, với tên của bạn trên commit đó.

Các tài liệu tiêu chuẩn nói thẳng về những gì đang được đặt cược. Thông tin cho người dùng được thiết kế tốt không chỉ làm giảm chi phí hỗ trợ; nó còn nâng cao uy tín của sản phẩm và của nhà sản xuất. Có được điều đó bằng cách đưa kiểm tra xác minh và kiểm tra xác nhận vào trong quá trình phát triển, chứ không phải sau khi đã xong Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF hiểu điều đó theo đúng nghĩa đen: tài liệu là một bề mặt sản phẩm có ngưỡng chất lượng, chứ không phải một phần phụ cho có lệ gắn vào mã nguồn.

Bản tóm tắt

NextPDF giữ những tài liệu này theo một mô hình chất lượng thông tin rõ ràng, rút ra từ các tiêu chí thông tin cho người dùng ở §8: một trang phải chính xác về mặt kỹ thuật, dùng một bộ từ vựng nhất quán, dễ hiểu với người đọc mà nó hướng đến, chỉ nói những gì cần thiết nhưng không bỏ sót bất cứ điều gì bắt buộc, và người dùng công nghệ hỗ trợ vẫn tiếp cận được Spec: ISO/IEC/IEEE 26514, §8 .
Cấu trúc không phải là thứ ứng biến. Các chủ đề được sắp xếp vào một hệ thống phân cấp cố định kèm metadata (mục, đối tượng, mức bằng chứng) để người đọc có thể tìm thấy một trang bằng cách nhận diện Spec: ISO/IEC/IEEE 26514, §9 , và phát biểu quan trọng nhất nằm gần đầu mỗi trang Spec: ISO 24495-1, §5 .
Giọng văn được điều phối bằng một hệ thống phân cấp văn phong đã phê chuẩn — Apple cho giọng điệu, Microsoft cho quy trình, Google cho mã, và ngôn ngữ giản dị bao trùm tất cả — được ghi ngay trong repo cùng với điều khoản gốc mà mỗi điểm khác biệt ghi đè.
Chất lượng được kiểm tra bằng máy. Vale thực thi các gói giọng văn; một bộ cổng composer docs:* thực thi tính toàn vẹn của liên kết, độ sạch của trích dẫn, việc không dùng nguyên văn văn bản tiêu chuẩn, và việc không rò rỉ chi tiết riêng tư.
Tài liệu được phát triển cùng với mã, theo từng vòng lặp — mỗi thay đổi đi kèm tài liệu của nó, chứ không bị dồn lại thành một khối tồn đọng Spec: ISO/IEC/IEEE 26515, §Introduction .

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

Một mô hình chất lượng, được viết ra

“Tài liệu tốt” là điều không thể kiểm chứng cho đến khi bạn gọi tên những thuộc tính cụ thể. NextPDF phát biểu lại các tiêu chí thông tin cho người dùng ở §8 theo cách diễn đạt của riêng mình, làm ngưỡng để đo từng trang Insider_: mỗi trang phải chính xác về mặt kỹ thuật, giữ một bộ từ vựng nhất quán, dễ hiểu với người đọc mà nó hướng đến, chỉ chứa những gì người đọc đó cần mà không bỏ sót bất cứ điều gì bắt buộc, và người dùng công nghệ hỗ trợ vẫn tiếp cận được Spec: ISO/IEC/IEEE 26514, §8 . Đó không phải là những tính từ; chúng là tiêu chí thẩm định. Phép thử “cần nhưng đầy đủ” là lý do một trang nêu rõ ranh giới của mình rồi dừng lại, thay vì viết lan man cho dài. Tính nhất quán của từ vựng là lý do thuật ngữ được điều phối (xem bên dưới). Khả năng tiếp cận là lý do mọi thành phần đều an toàn với bàn phím và trình đọc màn hình, và không bao giờ chỉ ra tín hiệu chỉ bằng màu sắc.

Cấu trúc dựa trên phân tích, không phải theo sở thích

Hệ phân loại Insider_ được đóng băng trước khi viết bất kỳ trang nào. Đó là quyết định có chủ ý. ISO 26514 yêu cầu việc phân tích đối tượng và tác vụ phải đi trước việc thiết kế thông tin Spec: ISO/IEC/IEEE 26514, §9 . Tiêu chuẩn này cũng yêu cầu các chủ đề phải được sắp xếp thành các hệ thống phân cấp hoặc nhóm, mỗi thứ mang metadata nhận diện đối tượng và loại thông tin của nó, để người dùng nhanh chóng tìm ra thứ họ cần Spec: ISO/IEC/IEEE 26514, §9 . Trong repository này, metadata đó là front-matter cụ thể — section, audience, evidence_level, tags — và bản đồ cụm là một tệp cố định duy nhất. Người đọc chọn một trang bằng cách nhận diện; không ai phải nhớ lại một slug.

Bên trong một trang, thứ tự được cố định và nhất quán ở mọi nơi, và phát biểu hữu ích nhất được đặt ở nơi người đọc bắt gặp đầu tiên — thường là phần mở đầu Spec: ISO 24495-1, §5 . Đó là lý do mỗi trang Insider_ đặt Bản tóm tắt trước phần chi tiết: người đọc có thể dừng lại sau ba mục mà vẫn có được một câu trả lời có cơ sở để bảo vệ.

Một hệ thống phân cấp văn phong có bằng chứng

Giọng văn không bị bỏ mặc cho tâm trạng của người viết. Repository mang theo một bảng ghi đè đã phê chuẩn (docs/style/nextpdf-overrides.md) đặt Apple (giọng điệu), Microsoft MSTP (quy trình và thuật ngữ giao diện), và Google DDSG (mã và CLI) lên trên các chuẩn nền về ngôn ngữ giản dị và từ vựng có kiểm soát, kèm một bảng giải quyết xung đột theo từng chế độ. Quy tắc nghiêm ngặt nhất của nó ghi đè lên tất cả: không có văn bản nguyên văn từ một tổ chức tiêu chuẩn có bản quyền. Mỗi điểm mà NextPDF đi lệch khỏi một hướng dẫn gốc đều được ghi lại cùng với điều khoản gốc mà nó ghi đè và lý do. Bảng văn phong trích dẫn các nguồn của chính nó theo đúng cách một trang vẫn làm.

Chất lượng bạn không cần phải tin theo cảm tính

Tính kỷ luật được thực thi bằng công cụ, không phải bằng thiện chí:

Scaffold The page starts from a populated front-matter and section skeleton.
Vale packs Apple, MSTP, Google, and controlled-vocabulary rules run on the prose.
Link check docs:link-check rejects link rot against the built site.
NDA scan docs:nda-scan rejects private FQCNs and internal artefact names.
Quote fingerprint docs:jaccard-fingerprint flags verbatim standards-text reuse.
Citation audit docs:rag-citation-check / docs:rag-fallback-check guard the digests.
Review A reviewer confirms the page's declared evidence level holds.

Các cổng chất lượng tài liệu, theo thứ tự một trang đi qua chúng: một khung sườn đã điền đầy cố định cấu trúc; Vale thực thi các gói giọng văn; các cổng docs:* thực thi tính toàn vẹn của liên kết, sự sạch sẽ trong trích dẫn, không có văn bản tiêu chuẩn nguyên văn, và không rò rỉ chi tiết riêng tư; bước thẩm định xác nhận cơ sở bằng chứng. Một trang không qua được một cổng là một lỗi, được xử lý như một bài kiểm thử thất bại.

Những thứ này ánh xạ tới các mục thật trong composer.json của repository này. docs:lint chạy cục bộ các cổng NDA và cổng liên kết. docs:jaccard-fingerprint đánh dấu việc tái sử dụng nguyên văn văn bản tiêu chuẩn vượt một ngưỡng tương đồng. docs:rag-fallback-check là một bộ thực thi giao thức toàn vẹn trích dẫn đã được hiện thực đầy đủ, ngoại tuyến và xác định. Việc tái xác minh RAG trực tiếp (docs:rag-citation-check) và một số bộ quét đã được nối dây làm cổng, còn những trình chạy sâu hơn của chúng thì vẫn đang được xây dựng. Phát biểu trung thực là thế này: bản giao kèo đã được phê chuẩn và các kiểm tra cấu trúc đã được thực thi ngay hôm nay; chiến dịch làm cho mọi kiểm tra trở nên đầy đủ vẫn đang tiếp diễn. Insider_ không tuyên bố một bảng điều khiển xanh mà nó chưa đạt được — bản thân điều này chính là tiêu chí “chính xác” của mô hình chất lượng đang áp dụng cho trang này.

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

Trang này là Evidence: Standard-backed cho các tuyên bố về chất lượng tài liệu và dựa vào repo cho các tuyên bố về việc thực thi. Cơ sở kép này là có chủ ý: các nguyên tắc đến từ các tiêu chuẩn; còn việc thực thi có thể kiểm chứng bằng cách đọc repository.

Tuyên bố	Cơ sở	Mỏ neo
Tài liệu có một ngưỡng chất lượng được định nghĩa	Tiêu chuẩn	Chính xác, một bộ từ vựng, người đọc hiểu được, cần nhưng đầy đủ, công nghệ hỗ trợ tiếp cận được Spec: ISO/IEC/IEEE 26514, §8
Thuật ngữ được điều phối	Tiêu chuẩn	Thuật ngữ nhất quán xuyên suốt tập thông tin Spec: ISO/IEC/IEEE 26514, §8
Cấu trúc đi trước việc viết	Tiêu chuẩn	Phân tích đối tượng và tác vụ trước khi thiết kế Spec: ISO/IEC/IEEE 26514, §9
Phát biểu hữu ích nhất đến trước tiên	Tiêu chuẩn	Thông điệp quan trọng nhất ở phần mở đầu Spec: ISO 24495-1, §5
Tài liệu đi kèm với mã	Tiêu chuẩn	Các sản phẩm bàn giao của mỗi vòng lặp bao gồm thông tin cho người dùng Spec: ISO/IEC/IEEE 26515, §Introduction
Chất lượng được kiểm tra bằng máy	Trong repo	`composer.jsondocs:*` các cổng; bản đã phê chuẩn `docs/style/nextpdf-overrides.md`; cấu hình Vale đang hoạt động

Ví dụ thực tế

Tính kỷ luật thể hiện ở quy mô nhỏ nhất: một dữ kiện chất lượng không bao giờ được gõ tay vào văn xuôi, vì một con số nằm trong văn xuôi sẽ âm thầm trở nên lỗi thời. Nó được kết xuất bởi một thành phần từ chối bịa ra một giá trị và được hậu thuẫn bằng cơ sở bằng chứng của trang:

<?php

declare(strict_types=1);

// Illustrative: the documentation build's contract for a quality datum.
// The component throws if no real value is supplied — a metric is never
// allowed to live as a hardcoded literal that can drift out of date.
final class QualityDatum
{
    public function __construct(
        public readonly string $label,
        public readonly string $value,
    ) {
        if ($this->value === '') {
            throw new \InvalidArgumentException(
                'A quality datum must carry a verified value; '
                . 'documentation never invents a metric.',
            );
        }
    }
}

$phpstanLevel = new QualityDatum(label: 'PHPStan', value: 'Level 10');

Điểm mấu chốt là lệnh throw. Tiêu chí “chính xác” của mô hình chất lượng thông tin ở đây không chỉ là khuyến nghị; cấu trúc thực thi tiêu chí đó để một con số lỗi thời không thể âm thầm lọt ra ngoài.

Hiểu lầm thường gặp

Cái bẫy là hiểu “tài liệu như một sản phẩm” thành một khẩu hiệu về sự bóng bẩy — văn hay hơn, trang đẹp hơn. Nó hoàn toàn ngược lại với chuyện trang trí bề ngoài. Nó có nghĩa là tài liệu mang theo một ngưỡng chất lượng đã định, một bộ từ vựng được điều phối, một cấu trúc cố định, và các cổng được kiểm tra bằng máy. Một trang không qua được bất kỳ cổng nào trong số đó là một lỗi cần được sửa, được xử lý như một bài kiểm thử thất bại. Sự trau chuốt là sản phẩm phụ của tính kỷ luật, không phải mục đích của nó.

Cái bẫy thứ hai là cho rằng mọi cổng đều đã đầy đủ chỉ vì bản giao kèo đã tồn tại. Không phải vậy, và trang này nói thẳng điều đó. Các kiểm tra cấu trúc đã được thực thi ngay hôm nay; những bộ xác minh sâu hơn đang được xây dựng dần. Khẳng định điều ngược lại sẽ vi phạm chính mô hình chất lượng mà trang này mô tả.

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

Trang này mô tả tính kỷ luật trong việc làm tài liệu. Nó không phải là bảng văn phong, tệp phân loại, hay bản thân các phần triển khai cổng. Nó không khẳng định bất kỳ hành vi nào của engine. Các tạo phẩm có thẩm quyền nằm trong repo (docs/style/nextpdf-overrides.md, hệ phân loại cố định, composer.json và các script docs:* của nó) và sẽ thay thế bất kỳ tóm tắt nào ở đây nếu có khác biệt.

Phạm vi thực thi vẫn còn từng phần, và điều này được thừa nhận thẳng thắn. Kiểm tra dự phòng về tính toàn vẹn của trích dẫn đã hoạt động. Các cổng liên kết và NDA chạy cục bộ. Các bộ xác minh trích dẫn nguyên văn và trích dẫn trực tiếp đã được nối dây, còn những trình chạy đầy đủ của chúng thì vẫn đang được hoàn thiện. Điều này được báo cáo là đang tiến hành, không phải đã hoàn tất. Ở những chỗ trang này chạm đến tài liệu bậc Premium, tính kỷ luật được mô tả áp dụng ở cấp độ quy trình, không bao giờ ở cấp độ của bất kỳ cơ chế không công khai nào.

Tài liệu liên quan

Kỷ luật trích dẫn — quy tắc nghiêm ngặt nhất trong hệ thống phân cấp văn phong, cùng hệ thống mức bằng chứng mà trang này dựa vào.
Bức tranh toàn cảnh về tiêu chuẩn — những tiêu chuẩn mà tính kỷ luật này trích dẫn, và cách một điều khoản trở thành hành vi được ghi nhận trong tài liệu.
Triết lý thiết kế của NextPDF — gu kỹ thuật xem một lỗi tài liệu như một lỗi mã.

Thuật ngữ

Mô hình chất lượng thông tin — cách NextPDF phát biểu lại các tiêu chí thông tin cho người dùng ở §8 của ISO 26514 (chính xác, một bộ từ vựng, người đọc hiểu được, cần nhưng đầy đủ, người dùng công nghệ hỗ trợ tiếp cận được) được dùng làm ngưỡng thẩm định cho mọi trang Insider_.
Ngôn ngữ giản dị — cách truyền đạt có cách dùng từ, cấu trúc và thiết kế giúp người đọc mục tiêu tìm thấy, hiểu và sử dụng được nội dung; một chuẩn nền áp dụng xuyên suốt các chế độ, chứ không phải một loại nội dung.
Hệ thống phân cấp văn phong — bộ hướng dẫn văn phong gốc đã phê chuẩn, xếp theo lớp (Apple, Microsoft, Google, cùng các chuẩn nền ngôn ngữ giản dị và từ vựng có kiểm soát), với mỗi điểm khác biệt của NextPDF được ghi lại kèm nguồn của nó.
Cổng chất lượng — một kiểm tra tự động (một gói Vale hoặc một script composer docs:*) mà một trang phải vượt qua; một lần không qua là một lỗi tài liệu, không phải chuyện nhỏ.
Metadata front-matter — phần đầu trang có thể đọc bằng máy (section, audience, evidence_level, tags) giúp một trang có thể định vị và phân loại được, theo yêu cầu về tổ chức chủ đề.