technical-writing

技术写作：先快速浏览，再决定是否读完

开发者会先快速浏览，再决定是否投入时间。文档要想让读者完整读完，就必须在首屏回答三个问题：这是什么？为什么值得关注？如何开始？以下所有内容都服务于这个约定。

资源	适用时机……
resources/doc-types.md	选择要写哪种页面——Diátaxis 的四种模式、教程与操作指南的区别、模型未涵盖的类型，以及按类型设定的精简原则
resources/readme.md	编写或全面改写 README——认知漏斗、长短取舍的结论、README 驱动开发
resources/docs-quality.md	让文档可检查、可执行——文案 lint、可执行示例、链接检查、摩擦日志、常青文档、每页都是起点
resources/agent-docs.md	为 AI Agent 编写文档——对 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 负责，维护中的流程由软件包或运维文档负责，领域词汇由权威词汇表负责。
• 不要让维护中的文档依赖已删除的规范，也不要依赖未作说明的交付标识符。确实需要引用问题、PR、任务、需求、规范或 ADR 标识符时，先用通俗语言说明其目的。
• 为文档索引提供明确的起点，并区分当前权威内容、进行中的工作、决策和历史证据。优先选择一组精简且便于导航的可信页面；删除重复、过时、推测性、自动生成或无人负责的文字。
• 仅修改文档并不意味着必须采用 TDD。任何可执行的文档检查仍需有针对性测试，证明它确实能失败。

同时为 AI Agent 撰写文档

开发者文档现在面向两类读者。便于 Agent 阅读意味着：

• 可枚举，而非只有叙述性文字：Agent 必须从中作出选择的内容——选项、标志、退出代码、状态——都应列在表格行中，不能只出现在段落里。
• 为每项操作说明前置条件和后置条件：操作前必须满足什么、操作后会发生什么、退出代码代表什么。对于两类读者，状态机表格（“处于状态 X 时，唯一正确的下一步操作是 Y”）都比叙述性文字更有效。
• 使用精确字符串：Agent 和处于紧急状态的人类读者都会复制粘贴。提供精确的命令、配置块和错误消息，绝不要改述。

文档类型

• README / 着陆页：首屏回答是什么、为什么以及如何开始；只有在能显著改善导航时才添加目录；快速入门应按真实顺序构成连贯流程；在致谢之前如实说明限制。
• 教程：开头就说明目标（“你将完成 X 并使其正常运行”）；步骤编号；展示每一步的输出，让读者知道进度是否正常；结尾说明接下来可以做什么。
• 参考文档：完整性优先于叙述；每个标志、选项、状态各有一条；尽可能自动生成；使用便于 Agent 阅读的表格。
• 提案 / 设计文档：开头说明需要作出的决策；如实呈现各选项的取舍；给出有理有据的建议，以及哪些证据会促使你改变建议。
• PR 描述 / 发布说明：说明变更对读者产生了什么影响（行为、迁移），而不是改写提交日志。

边界

情况	技能
选择和编写图表	diagrams
REST/API 参考语义（错误、分页、版本控制）	api-design
CLI 帮助文本、退出代码、输出设计	cli-design
趁记忆犹新时记录预期、注意事项和决策	expectations
正文中的领域词汇	ubiquitous-language（如已安装）
句子层面的语气、通用文案或 AI 风格写作	clarity（如已安装）
简明英语、面向普通读者、翻译或 ASD-STE100	simple-english（如已安装）

验证清单

• 首屏说明是什么、为什么以及如何开始
• 标题概括收益；适用时提供目录，并通过机器检查其锚点
• 重要的能力、当前状态和量化声明均附有依据或日期；宣传性声明均有证据支持
• 读者会依赖的命令、标志和可执行示例均对照源代码验证，并在可行时实际运行
• 在暗示的范围可能造成误导之处，说明重要限制
• 可枚举的信息以表格呈现；所有可复制粘贴的内容均提供精确字符串
• 计数和版本遵循持续更新规则，或由程序生成
• 文档变更与其描述的行为变更一同提交评审
• 维护中的文档描述当前事实；已完成或已被取代的工作区应删除
• 长期约束应记录在当前负责人维护的文档中，而不应只存在于历史交付材料中
• 索引应区分当前权威资料、进行中的工作、决策和历史记录