把文档当作产品

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

概览

这些页面依照一套文档质量模型构建，遵循平实语言基线和分层的风格层级撰写，并由与引擎代码同类的自动化关卡核查。本页解释这套纪律，以及为什么文档缺陷会被记录为工程缺陷。

它面向这样的资深工程师：曾被自信满满却无法验证的文档坑过，因此在信任这些文档之前，想先弄清它们究竟有何不同。

为什么这很重要

一套文档库靠信任被采用，而文档正是这份信任被给予或被收回的地方。一个页面如果以你察觉不到的方式出错，比根本没有这个页面还要糟糕。它会把你的谨慎变成放错地方的自信。问题在生产环境中暴露出来，而那次提交上署着你的名字。

标准文献对其中的利害关系毫不含糊。精心设计的用户信息不仅能降低支持成本——它还能提升产品及其生产者的声誉。要做到这一点，靠的是把验证测试和确认测试放进开发过程之中，而不是放在它之后 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（操作步骤和界面术语）以及 Google DDSG（代码和命令行），并附有一张按模式划分的冲突裁决表。其中最严格的一条规则高于所有其他规则：不得逐字照搬出自持有版权的标准机构的文本。关键在于，每一处 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:* 脚本），一旦它们与此处的任何摘要有出入，便以它们为准。

坦率地说，强制执行目前只覆盖一部分。引用完整性的兜底检查已经上线。链接关卡和保密协议关卡在本地运行。逐字引用验证器和实时引用验证器已经接入，但用于完整覆盖的运行器仍在落地之中。这里如实报告为进行中，而非已完成。本页凡涉及 Premium 层级文档之处，所描述的纪律只适用于流程层面，绝不适用于任何非公开机制的层面。

术语表

信息质量模型 —— NextPDF 对 ISO 26514 第 §8 节用户信息准则（准确、单一术语、读者可理解、所需但完整、辅助技术可达）的重述，用作每个 Insider_ 页面的评审标尺。
平实语言 ——一种沟通方式，其措辞、结构和设计让目标读者能够找到、理解并使用相应内容；它是一条贯穿各类模式的基线，而不是一种内容类型。
风格层级 ——一套经过批准、分层叠加的上游风格指南（Apple、Microsoft、Google，外加平实语言基线和受控术语基线），其中每一处 NextPDF 的偏离都对照其来源逐一记录在案。
质量关卡 ——每个页面必须通过的一项自动化检查（一个 Vale 包或一个 composer docs:* 脚本）；未通过就是文档缺陷，而不是无关紧要的小毛病。
前置元数据 ——机器可读的页眉（section、audience、evidence_level、tags），它依照主题组织要求让一个页面可被定位、可被分类。