doc-refine — 技术文档阅读体验优化指南
审阅与改写边界
先区分审阅和改写：只要求审阅时提供问题与建议；已明确要求修改时，只改授权文档。涉及行为或事实变化而非表达调整时，保留原意并指出需要确认的部分。
精简前保护：技术行为、API/数据契约、前提与边界条件、安全及法律警告、无障碍替代说明、有效示例、来源链接和稳定锚点。代码里已有同样行为，不足以证明文档可以删除；局部必要重复可以帮助独立阅读。
两个检查目标
所有判断最终归约为两个问题：
| 公理 | 问自己的问题 | 一句话 |
|---|---|---|
| ① 快速找到 | 目标读者能从目录与标题判断信息在哪吗？ | 路标清晰 |
| ② 每段有用途 | 删掉后是否损失完成任务、理解行为或控制风险所需的信息？ | 信息完整且精练 |
对每一段内容执行这两个校验。不满足 ① → 改标题/加图表/调结构。 不满足 ② → 核对保护项与读者任务，再建议合并或精简；不以篇幅为由删除必要内容。
工作流
1. 诊断（先读全文，不急着改）
通读目标文档，逐 section 记录问题：
- 标题能否脱离编号独立传达内容？（不→公理 ① 违反）
- 同一逻辑/规则在 2+ 处出现？（是→公理 ② 违反）
- 这段行为说明是否帮助使用者理解契约、限制或结果？先判断用途，不按“是什么/为什么”机械删除。
- 引导语是否只有重复铺垫？可精简措辞，但保留其中的步骤定位、警告或限制。
- 3+ 项对比散落在散文里？（是→该用表格）
- 图是否比文字更容易理解流程或状态？按目标渲染器能力选 Mermaid 或保留文字。
- 示例是否解决真实疑问、错误恢复或边界情况？保留对目标读者有效的示例。
2. 修复（按公理分类施加）
具体规则见下方 §公理 ① 和 §公理 ②。
3. 校验（量化基准）
修复后按需读取 校验清单，检查信息完整性与阅读效果。 不是每个数字都必须达标——它们是诊断工具而非法律，清晰优先时可破例。
公理 ①：快速找到
标题辨识度
标题是路标。维护者扫 TOC 时应该一眼知道每个 section 装了什么。
判断标准：如果你需要点进 section 才知道它讲什么，标题太泛了。
| ❌ 太泛 | ✅ 可辨识 | 为什么改 |
|---|---|---|
5.1 表级 | 5.1 项目 CRUD（表级端点） | "表级"可以是任何东西 |
5.3 行级 | 5.3 行级协作端点 | 读者知道这里有认领/交付等操作 |
5.4 导出 | 5.4 全量 CSV 导出 | 什么格式？全量还是部分？ |
端点 | HTTP 端点 | 消除歧义 |
技巧：核心概念太短时，加括号限定词补充关键信息。但别过度—— 目标是 ≤15 个字传达"这节有什么"，不是写论文标题。
信息架构
- 一节一职：以教程、操作、参考或解释的主要读者任务组织内容；需要的 API 签名或简短背景可以保留，长篇资料用交叉链接。
- 核心在前，细节在后：最重要的信息放在 section 开头或文档顶部 （Progressive Disclosure）。高级/边缘信息可以折叠或放附录。
- 自足原则：维护者从任何一页开始读都不需要"前序知识" （Every Page is Page One）。需要前置概念时，在 section 顶部声明并加链接。
图表替代文字
当关系、顺序或对比用图更清楚时再用图；保留可检索文字与必要的替代说明。
决策树：
信息类型是？
├─ 多步骤流程 / 有分支判断 → 流程图（flowchart）
├─ 事件驱动的状态变化 → 状态图（stateDiagram-v2）
├─ 3+ 项 × 2+ 维度对比 → 表格
├─ 组件关系 / 架构层级 → 示意图 + 分层
├─ 定义 / 上下文 / 精确数值 → 文字（默认）
└─ 不确定 → 默认文字（图是锦上添花非装饰）
Mermaid 最佳实践：
- 节点 ≤30——超出后布局算法不可读，拆"概览→细节"多图
- 为分支条件和含义不清的关系加标签；清楚的顺序箭头可不标，避免标签噪音
- 用
subgraph分组相关节点 TD（自上而下）适合层级；LR（从左到右）适合序列/管线
表格设计（Tufte 原则）：
- 删除不必要的线、底纹、纯装饰——"Above all else show the data"
- 最小有效差异：视觉区分尽可能微妙但清晰
- 数字按列对齐便于扫描比较
- 文字始终水平，禁止竖排
公理 ②：每段有用途
消重
同一信息出现在多处是可维护性的头号敌人——改了一处忘了另一处。
检测标准（命中任一条 → 需要消重）：
- 同一段逻辑/规则在 2+ section 出现 → 留权威源（通常是数据模型或状态机节），其余改交叉引用
- 核对行为、前提、风险与独立阅读后，确无信息损失的段落 → 合并或精简
- 文档重复实现细节 → 判断读者是否需要；保留行为说明与契约，不以代码已有为删除理由
- 多种等价做法 → 给出默认建议；保留兼容性、权限或使用条件不同的必要替代
ARID ≠ DRY：文档接受必要的重复——教程里重述参考节的概念是合理的。 但消除平行维护：同一个事实不能在两处独立维护，否则必有一处过时。
精简
砍掉一切不为读者当前需求服务的内容。
| 坏味道 | 修法 | 为什么 |
|---|---|---|
| 重复铺垫："在本节中我们将讨论…" | 合并为直接表述 | 保留必要的步骤定位 |
| 填充词："需要注意的是" / "值得一提的是" | 精简引导语 | 警告或限制本身仍须保留 |
| 被动语态连篇（"被用于…""将会被…"） | 改主动 SVO | 更短、更清晰、读者知道"谁在做什么" |
| 同义词漂移（同一功能用不同词） | 统一术语，一词一义 | 让读者明确同一功能的名称 |
| 难读的长嵌套句 | 按逻辑拆句 | 不拆散条件、例外与结论的关系 |
| 列举等价方案 | 推荐方案在前，必要替代随后 | 保留不同约束下的可行选择 |
示例克制
示例是最强的速答工具，也是最容易被滥用的内容类型。 Write the Docs 特意写 "Include (some) examples"——括号里的 "some" 是刻意的限定。
该用示例的时机：
- 读者需要快速答案，会直接跳到示例（很多人的第一反应）
- 概念没有具体例子就难以理解
- 演示的是高频、真实的用例
不该用示例的时机：
- 在演示显而易见的东西（Microsoft: "Don't illustrate obvious points"）
- 无助理解的人为场景；清楚标记且能验证行为的合成示例可以保留
- 仅为"完整性"而加，没有用户真实需求驱动
- 示例已经够多了——再加会降低可扫描性
好示例：
- 只覆盖最常见用例，不穷举
- 自包含且可运行（复制粘贴就能工作）
- 从简单到复杂递进
- 展示预期输出让读者验证
- 仅在示例仍可运行或已明确前提时省略样板；保留必要 import、错误处理与预期输出
坏示例：
- 演示显而易见的东西
- 不真实的人造场景
- 一个示例试图覆盖太多变量
- 塞入与示例无关的异常处理
- 未验证却声称可运行的代码；无法运行时明确标注验证限制
位置规则：
- 简单的一行示例 → 内联在正文中
- 较长的示例 → 与密集参考资料分离（独立段落或折叠区）
- 参考文档中的示例 → 保持克制，只做用法说明，不混入教学
量化基准速查
以下仅为按语言和读者调整的初筛提示；详见 校验清单。
| 维度 | 建议起点 | 使用边界 |
|---|---|---|
| 英文句长 | 约 20 词后留意嵌套 | 不机械套用中文，不拆坏条件和契约 |
| 段落 | 一段一个主要观点 | 例外与警告可紧随原段 |
| 列表/步骤 | 较长时考虑分组 | 不为凑项数删除完整步骤 |
| 被动语态 | 主体不清时改写 | 不设必须达标的比例 |
| Mermaid | 节点多时考虑概览与细节 | 以实际渲染可读性判断 |
| 表格 | 宽表考虑拆分或转置 | 保留比较所需列与单位 |
数字是建议，不是行业合格标准或研究定律；不为达标改变事实、合同、安全或法律文本。
反模式速查
| 反模式 | 症状 | 解法 |
|---|---|---|
| Almighty Thud | 巨无霸文档，所有信息等权，关键决策被淹没 | 拆分或加优先级分层 |
| 类型混写 | 教程里塞 API 参考，参考里写"为什么" | 按 Diátaxis 拆开 |
| 重复铺垫 | 无实质信息的引导语 | 精简措辞，保留风险与步骤信息 |
| 同义词漂移 | 同一功能用不同词称呼 | 统一术语 |
| 关系不清 | 分支或箭头含义需猜测 | 为不明确的关系补标签 |
| chartjunk | 表格加多余装饰线、底纹 | 删除不传递信息的装饰 |
| 示例过载 | 穷举所有场景的示例 | 只留最常见用例 |
| 平行维护 | 同一事实在多处独立维护 | 留一处，其余改链接 |