技术写作：先被浏览，再被信任到读完
开发者会先快速浏览，再决定是否投入阅读。文档在首屏回答三个问题才能赢得完整阅读：这是什么、我为什么要在意、我如何开始。以下所有内容都服务于这一契约。
| 资源 | 何时加载 |
|---|---|
resources/doc-types.md |
选择要写的页面类型时——Diátaxis 四种模式、教程与操作指南的区别、模型常遗漏的类型、按类型划定的极简主义 |
resources/readme.md |
撰写或大改 README 时——认知漏斗、长短版本的取舍、README 驱动开发 |
resources/docs-quality.md |
让文档可强制执行时——散文 lint、可执行示例、链接检查、摩擦日志、永恒文档、每一页都是第一页 |
resources/agent-docs.md |
文档服务 AI 智能体时——对 llms.txt 的诚实判断、markdown 端点、可被 RAG 分块的页面 |
resources/formatting.md |
结构规则——标题、小标题、段落、列表、引言/结语、目录 |
resources/references.md |
上述每条论断的来源 |
每页一个主要读者任务
为页面选择主要读者任务：教程、操作指南、参考或解释（Diátaxis；其诚实的局限见 resources/doc-types.md）。当辅助材料有助于完成同一任务时，可以跨越边界。当混合目的导致下一步行动、完整性契约或目标读者不清晰时，应拆分页面。
原则
- 读者优先——先讲收益；读者的下一步行动是组织原则，而非系统的内部结构。用读者能识别的名称命名事物，而非代码的构建方式。
- 可扫描——清晰的小标题概括其所在部分的收益，短段落，有目的地强调。当小标题能为浏览者提供有用的地标时再加；不要为字数配额而优化。
- 简洁直接——主动语态，说明用第二人称，复杂观点用短句。完整句子胜过片段和箭号链：可读比简洁更重要。
- 选择性取舍，而非压缩——让文档短的方式是删掉不改变读者下一步行动的内容，绝不是把散文压缩成读者必须解码的术语。
实质性论断需要证据
让实质性的能力、当前状态、兼容性和量化论断可核查。解释性散文、明确标注的判断和规范性的设计理由不需要伪造的命令或日期；无支撑的推广性论断则需要。
- 无证据不得声称能力：读者可验证的数字、可运行的命令、可打开的文件。"快"是营销；"门禁在此仓库 CI 上运行需 14 秒"是有证据的论断。
- 计数和版本会腐坏：散文中引用的运营数字（测试数量、覆盖率、版本）是维护负担——要么生成它，要么标注日期，要么绑定到保持最新规则（更新它是每次变更完成定义的一部分）。
- 诚实的局限是内容，而非忏悔：当页面的范围可能暗示其并不提供的保护、覆盖或能力时，在读者做决定的地方点明这些局限。当受限的范围已明确时，短文档不必长出仪式性的局限章节。
- 空闲和空状态必须说话：读起来像成功的"已处理 0 项"是版面的谎言。在文档和示例中所有出现输出的地方区分"无事可做"和"什么也没做"。
- 永恒维护的指引：常青的 README 和参考文档避免无主的"即将推出"、"当前"或"新增于…"标签。发布说明、迁移指南、弃用通知和时间受限的状态页可能需要时间性语言；附上版本/日期和负责人或移除条件，使其仍是证据而非陈旧的推广。
文档即行为——验证它们
描述系统的文档就是关于该系统的论断，而论断需要验证：
- 对照源头而非记忆验证：文档要求读者依赖的每个实质性标志、退出码、配置键和可执行命令，在发布前都要对照代码检查。在安全、获授权且相称时执行该论断；否则记录证据缺口。
- 机器能检查的就让机器检查：目录锚点对照渲染器真实的 slug 规则，链接对照文件，命令示例对照二进制文件。手工验证是后备，不是默认。
- 在同一可审查的变更中更新文档：行为变更若留下过时文档，就是未完成的工作。遵循仓库的提交策略，而非全局强加一套。
受维护的文档描述当前事实
完整的基于状态的生命周期和 Git 考古工作流见 resources/docs-quality.md。
- 计划与规范工作区仅在其成果尚未完成时保留。成果交付或其假设被取代时删除；Git 历史即档案。
- 持久的约束提升给其当前所有者：行为归源码或可执行测试，架构决策归已接受的 ADR，受维护的流程归包或运维文档，领域词汇归权威术语表。
- 不要让受维护的文档依赖已删除的规范或未解释的交付标识符。在引入任何确实必要的 issue、PR、任务、需求、规范或 ADR 标识符之前，先用平实语言说明其目的。
- 给文档索引一个清晰的起点，并区分当前权威、进行中的工作、决策和历史证据。优先选择一小组可导航的可信页面；删除重复、过时、推测性、自动生成或无主的散文。
- 仅文档变更本身不需要 TDD。任何可执行的文档守卫仍需一个能证明它会失败的聚焦测试。
也为 AI 智能体写作
开发者文档如今有两类受众。智能体可读意味着：
- 可枚举胜过纯散文：智能体必须从中选择的内容——选项、标志、退出码、状态——出现在表格行中，而不仅在段落里。
- 每个操作的前置条件和后置条件：之前必须为真什么，之后变化什么，退出码含义是什么。状态机表（"处于状态 X 时，唯一正确的下一步是 Y"）对两类受众都胜过叙述。
- 精确字符串：智能体（和有压力的人）会复制粘贴。给出确切的命令、确切的配置块、确切的错误消息——绝不要转述。
文档形态
- README / 落地页：首屏回答是什么/为什么/如何开始；当目录能实质性改善导航时加目录；快速开始是一条按真实顺序排列的连贯旅程；诚实的局限放在致谢之前。
- 教程：开头说明目的地（"你将让 X 运转起来"）；编号步骤；展示每一步的输出，让读者知道自己在正轨上；结尾给出下一步去向。
- 参考：完整性胜过叙述；每个标志/选项/状态一条条目；尽可能自动生成；智能体可读的表格。
- 提案 / 设计文档：开头给出所请求的决策，带诚实权衡的选项，带推理的建议，以及什么证据会改变它。
- PR 描述 / 发布说明：面向该变更的读者说明变了什么（行为、迁移），而非提交日志的转述。
边界
| 情况 | 技能 |
|---|---|
| 选择与创作图表 | diagrams |
| REST/API 参考语义（错误、分页、版本控制） | api-design |
| CLI 帮助文本、退出码、输出设计 | cli-design |
| 趁记忆新鲜时记录预期、坑点、决策 | expectations |
| 散文中的领域词汇 | ubiquitous-language（如已安装） |
| 句级语气、通用散文或 AI 化写作 | clarity（如已安装） |
| 简明英语、普通读者、翻译或 ASD-STE100 | simple-english（如已安装） |
验证清单
- [ ] 首屏回答是什么 / 为什么 / 如何开始
- [ ] 小标题概括收益；在需要处有目录，且其锚点经机器检查
- [ ] 实质性能力/当前状态/量化论断带有证据或日期；推广性论断有依据
- [ ] 读者依赖的命令、标志和可执行示例已对照源头验证，并在可行时运行
- [ ] 在隐含范围可能误导之处，点明实质性局限
- [ ] 可枚举的事实出现在表格中；任何可复制粘贴的内容给出精确字符串
- [ ] 计数/版本绑定到保持最新规则或自动生成
- [ ] 文档变更与其描述的行为搭乘同一可审查的变更
- [ ] 受维护的文档描述当前事实；已完成或被取代的工作区已删除
- [ ] 持久约束与其当前所有者共存，而不仅在历史交付物中
- [ ] 索引区分当前权威、进行中的工作、决策和历史