3.4 KiB
3.4 KiB
文档审查与完成标准
审查以读者能否完成目标为依据。每个问题给出位置、具体证据、读者影响和建议；只给“太简单”“不够专业”无法指导修改。
问题优先级
| 级别 | 判断 | 例子 | 处理 |
|---|---|---|---|
| 阻断 | 使读者得到错误语言规则、用法或验证结论 | 宣称 get 已内置；把导入写成授权；伪造运行结果 | 修复后才能称为完成 |
| 重要 | 缺少完成当前任务所需的信息 | 例子依赖不存在的声明；核心规则无法定位 | 本任务内补足，或准确说明受阻部分 |
| 改进 | 内容正确，表达或查找仍可优化 | 链接文案不明确；重复背景 | 按收益修改，不无限扩大任务 |
| 偏好 | 多种同样可读的写法 | 无实际效果的标题风格差异 | 不当作缺陷，不强制改写 |
未定义的语言能力本身不一定是文档缺陷；把它写成已实现或让读者无法识别假设才是缺陷。
六个检查维度
- 目标与范围：页面能否回答一个明确问题？关键前提是否在当前读者可得的位置？
- 正确性与状态：每条语言断言是否有依据？文字、形式、例子、规范状态是否一致？
- 示例与结果：名称可追溯吗？条件、输入、效果和失败边界是否足以解释例子？
- 组织与检索：顺序阅读是否需要未介绍的概念？直接跳入是否能找到主定义和必要上下文？
- 表达与记法：术语是否统一？语句独立成立？视觉形式是否帮助识别关系？
- 维护与证据：影响页是否同步？来源可核对？测试等级与实际操作相符？
不把这些维度打成一个虚假的精确总分。交付记录“通过、发现问题或不适用”的依据；文档质量不能由行数、链接数或规则命中数量代表。
三个读者任务
复述任务：不借助聊天，说明本页对象、职责和一个主要边界。记录在哪个词或段落无法继续。
定位任务：从目录或直接落到页中，找到一个具体约束。例如“use 会不会改变当前归属？”记录路径和最终依据；没有真人参与时只称作者走查。
预测任务：改变例子中的一个条件，预测结果或合法性。例如将 alice:shop 换成 bob:shop 后是否仍为同一 namespace；为什么？
检查针对本次改动选择，微小错字无需重新评估全书。结构、语义或示例改动要执行相关任务。真实读者测试需要记录任务、参与者背景和实际反馈，不能用作者自查代替。
审查结果如何写
用“位置：断言或片段 → 违反的规则/缺少的前提 → 对读者的影响 → 最小修正”表达。区分确定缺陷与待确认问题。只列有证据的问题，不为凑数量虚构发现。
审查-only 任务到报告为止；带修复的任务先修正，再报告剩余问题。一次工作已满足目标且无未解决的相关阻断/重要问题时即可交付，不为了追求全书完美持续扩张。
完成证据
结构工具通过是最低的机械核对。具体改动还需有相应语义、读者任务或执行证据。报告中写明检查对象与限制，例如“走查导入参考的直接访问路径，已能在本页找到归属区别；未进行真人测试”。