把文件當成產品

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

概覽

這些頁面依循文件品質模型打造，以淺白語言為基準，並在分層的風格層級下撰寫；它們也會接受與引擎程式碼同類型的自動化關卡查核。本頁說明這套紀律，以及為什麼文件缺陷會被記錄為工程缺陷。

本頁寫給這樣的資深工程師：你曾被看似篤定卻無從驗證的文件坑過，因此在信任這些文件之前，想先弄清楚它們究竟有何不同。

為什麼這很重要

一套文件函式庫能被採用，靠的是信任；而文件正是這份信任被賦予或收回的地方。錯得讓你不易察覺的頁面，比根本沒有頁面更糟。它會把你的審慎轉化為放錯地方的信心，而錯誤會在正式環境中浮現，commit 上掛著你的名字。

標準文獻並未淡化其中的利害關係。設計精良的使用者資訊不只能降低支援成本，更能提升產品與其製作者的聲譽。要贏得這份聲譽，靠的是把驗證與確效測試納入開發流程，而不是等開發結束後才補上 Spec: ISO/IEC/IEEE 26513, §Foreword 。NextPDF 把這句話完全當真：文件是帶有品質門檻的產品介面，而不是附在程式碼上的客套。

精簡版

NextPDF 把這些文件約束在一套明確的 資訊品質模型 之下，該模型衍生自 §8 的使用者資訊準則：一個頁面必須在技術上準確、採用單一且一致的詞彙、能讓標明的讀者理解、只說必要之事卻不漏掉任何必備內容，並且對輔助技術始終可及 Spec: ISO/IEC/IEEE 26514, §8 。
結構不是臨場發揮。主題會被 編入帶有中繼資料的凍結式層級 （區段、受眾、證據層級），讓讀者可以靠辨識而非回想來找到所需內容 Spec: ISO/IEC/IEEE 26514, §9 ，而最重要的陳述則安排在每一頁靠前的位置 Spec: ISO 24495-1, §5 。
語氣由一套 正式核可的風格層級 管轄——語調採 Apple、程序採 Microsoft、程式碼採 Google，並以淺白語言作為貫穿全篇的基準——而且會在程式庫內留存記錄，連同每處偏離所推翻的上游條款一併記下。
品質由 機器查核 落實。Vale 落實這些語氣套件；一組 composer docs:* 關卡則落實連結完整性、引用衛生、不得逐字照搬標準文字，以及不得洩漏私密細節。
文件是 隨程式碼迭代開發 的——每次變更都連同相應文件一起交付，而非累積成待辦 Spec: ISO/IEC/IEEE 26515, §Introduction 。

NextPDF 如何看待這件事

明文寫下的品質模型

「好文件」在你說清楚它有哪些屬性之前，是無從證偽的。NextPDF 以自己的措辭重述 §8 的使用者資訊準則，作為衡量每一個 Insider_ 頁面的門檻：每一頁都必須在技術上準確、維持單一且一致的詞彙、能被其目標讀者理解、只承載該讀者所需而不漏掉任何必備內容，並對輔助技術始終可及 Spec: ISO/IEC/IEEE 26514, §8 。這些不是形容詞，而是審查準則。正是這項「必要但完整」的檢驗，會使頁面說清楚自己的邊界，然後就此打住，而不是灌水充數。詞彙一致性，也是術語必須受到管轄的原因（見下文）。可及性，也說明了為什麼每個元件都必須對鍵盤與螢幕報讀器友善，且絕不單靠顏色來傳達訊息。

結構出於分析，而非品味

Insider_ 的分類體系在任何頁面動筆之前就已凍結。這是刻意為之。ISO 26514 要求受眾與任務分析必須先於資訊的設計 Spec: ISO/IEC/IEEE 26514, §9 。它同時要求主題必須編入層級或群組，每一項都帶有可標明其受眾與資訊類型的中繼資料，好讓使用者迅速找到所需內容 Spec: ISO/IEC/IEEE 26514, §9 。在本程式庫中，那份中繼資料具體呈現在前置資料中：section、audience、evidence_level、tags；而叢集對應表則是單一一份凍結的檔案。讀者是靠辨識來選定頁面，永遠不必去回想某個 slug。

單一頁面內的順序固定，且各頁一致；最有用的陳述會擺在讀者最先看到的位置——通常就是開頭 Spec: ISO 24495-1, §5 。這正是為什麼每一個 Insider_ 頁面都把 精簡版 放在細節之前：讀者讀完三個小節後就可以停下，仍能帶走一個站得住腳的答案。

附帶憑據的風格層級

語氣不會交由撰稿者的當下心情決定。程式庫內有一份經正式核可的覆寫表（docs/style/nextpdf-overrides.md），在淺白語言與受控詞彙的基準之上，套疊 Apple（語調）、Microsoft MSTP（程序與 UI 術語）以及 Google DDSG（程式碼與 CLI），並附有逐模式的衝突解決對照表。其中最嚴格的一條規則凌駕於所有規則之上：不得逐字照搬任何有授權限制的標準機構文字。重點是，每一處 NextPDF 偏離上游指南之處，都會 連同它所推翻的上游條款與理由一併記錄下來。這份風格表引用自身來源的方式，與頁面引用來源的方式如出一轍。

不必憑空相信的品質

這套紀律是靠工具落實的，而不是靠善意：

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.

文件品質關卡，依一個頁面通過它們的順序排列：填妥的鷹架固定住結構；Vale 落實語氣套件；docs:* 關卡落實連結完整性、引用衛生、不得逐字照搬標準文字，以及不得洩漏私密內容；審查則確認證據基礎。任何未通過某道關卡的頁面都是缺陷，會被當成未通過的測試來處理。

這些項目對應到此程式庫 composer.json 中的真實項目。docs:lint 會在本機執行 NDA 與連結關卡。docs:jaccard-fingerprint 會標出相似度高於門檻的逐字標準文字重用。docs:rag-fallback-check 是一個已完整實作、離線且具決定性的引用完整性協議強制器。即時 RAG 重新驗證（docs:rag-citation-check）與部分掃描器已接入為關卡，但更深層的執行器仍在建置。誠實的說法是：契約已經核准，結構性查核今日已受強制執行；讓每項查核都達到完整覆蓋的工作仍在進行。Insider_ 不會宣稱自己尚未贏得一片綠燈的儀表板——而這本身就是把品質模型中的「正確」準則套用在本頁上。

證據說明了什麼

對於文件品質主張，本頁具備 Evidence: Standard-backed ；對於落實方式的主張，則以程式庫內證據為根據。這種雙重基礎是刻意安排的：原則來自標準；落實方式 則可透過閱讀程式庫來驗證。

主張	基礎	錨點
文件有明確定義的品質門檻	標準	準確、單一詞彙、讀者可理解、必要但完整、輔助技術可及 Spec: ISO/IEC/IEEE 26514, §8
術語受到管轄	標準	整個資訊集合使用一致術語 Spec: ISO/IEC/IEEE 26514, §8
先有結構，才開始撰寫	標準	先進行受眾與任務分析，再設計資訊 Spec: ISO/IEC/IEEE 26514, §9
最有用的陳述放在最前面	標準	最重要的訊息放在開頭 Spec: ISO 24495-1, §5
文件隨程式碼一起交付	標準	每次迭代的交付項目都包含使用者資訊 Spec: ISO/IEC/IEEE 26515, §Introduction
品質由機器查核	程式庫內	`composer.jsondocs:*` 關卡；經正式核可的 `docs/style/nextpdf-overrides.md`；以及生效中的 Vale 設定

實際範例

這套紀律在最細微的尺度上也看得出來——任何品質數據絕不會用手打進正文裡，因為正文中的數字會無聲無息地過時。它是由一個 拒絕憑空捏造數值 的元件呈現的，並以該頁面的證據基礎作為後盾：

<?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');

重點就在那個 throw。資訊品質模型的「正確」準則在此不是建議性的；它在結構上被強制執行，因此過時的數字無法悄悄出貨。

常見誤解

陷阱在於把「把文件當成產品」讀成一句關於打磨的口號——文字更漂亮、頁面更精美。它與表面功夫恰恰相反。它的意思是，這些文件帶有明確界定的品質門檻、受到管轄的詞彙、凍結的結構，以及由機器查核的關卡；任何未通過其中任一項的頁面，都是一個 有對應修正的缺陷，會被當成未通過的測試來處理。打磨是這套紀律的副產品，而非它的目的。

第二個陷阱，是因為契約已經存在，就假設每一道關卡都已經滴水不漏。事實並非如此，而本頁也直言不諱地這麼說。結構性的查核目前已經落實；更深層的驗證器仍在逐步建置中。若聲稱並非如此，反而會違背本頁所描述的那套品質模型本身。

限制與邊界

本頁描述的是文件紀律。它並不是風格表、分類體系檔案，或關卡實作本身。它並未斷言任何引擎行為。具權威性的成品都在程式庫內（docs/style/nextpdf-overrides.md、凍結的分類體系，以及 composer.json 的 docs:* 指令稿），一旦它們與此處的任何摘要有出入，便以它們為準。

我們坦承，目前只完成部分落實。引用完整性的退回查核已上線運作。連結與 NDA 關卡會在本機執行。逐字引文與即時引用的驗證器都已接好，但它們完整的執行器尚未到位。這一點據實呈報為進行中，而非已完成。當本頁觸及 Premium 層級文件時，所描述的紀律僅適用於流程層面，絕不適用於任何非公開機制的層面。

詞彙表

資訊品質模型 — NextPDF 以自己的措辭重述 ISO 26514 §8 的使用者資訊準則（準確、單一詞彙、讀者可理解、必要但完整、輔助技術可及），作為衡量每一個 Insider_ 頁面的審查門檻。
淺白語言 — 一種溝通方式，其用字、結構與設計能讓目標讀者找到、理解並運用內容；它是適用於所有模式的基準，而非某種內容類型。
風格層級 — 一套經正式核可的分層上游風格指南（Apple、Microsoft、Google，再加上淺白語言與受控詞彙的基準），其中每一處 NextPDF 的偏離都對照其來源加以記錄。
品質關卡 — 一項頁面必須通過的自動化查核（一個 Vale 套件或一支 composer docs:* 指令稿）；未通過即是文件缺陷，而非吹毛求疵的小毛病。
前置資料中繼資料 — 一段機器可讀的標頭（section、audience、evidence_level、tags），依循主題編排的要求，讓頁面得以被定位與分類。