Files
Endorphin-Document/authoring/tasks/TASK-07.md
T

2.1 KiB

TASK-07 审查文档

适用:检查质量、解释为什么难读、评审新章节或查找全书不一致。审查请求默认产出问题与建议;有修复授权时继续实施。

必读:审查标准、DOC-015、DOC-021、DOC-024。报告可用TPL-06。

先确定审查范围

记录目标页、相关主定义和预期读者。全书审查可先根据风险覆盖关键路径:语言定位、归属与导入、阶段、调用、数据、UI;对抽样范围作实际说明,不能将抽样称为逐页审查。

只查格式的任务可以限制在格式范围。语义审查需要读取规范状态及相关主定义,不能仅依据常见编程语言经验判断。

三遍阅读

第一遍作为新读者,尝试复述对象、作用和主要例子。第二遍按断言核对依据、状态、例子和文法。第三遍追踪跨页依赖、目录和局部条件。

每次发现问题先尝试最小修正思路。若问题实际来自未确定设计,将其标成设计缺口;若是文档把未知写成已知,则是确定的文档缺陷。

形成可执行发现

记录具体位置与原文主张,说明读者会得到什么错误理解,以及最小修正。按阻断、重要、改进排序,合并同源重复项但列出受影响位置。

例如:“函数页只展示 use 而没有被调用函数的定义,读者无法推导金额;补充声明或指向声明并写出输入与结果。”比“示例不够完整”可操作。

正面观察只有在说明哪些内容可保留时才有价值。没有发现实质问题就如实报告范围与剩余未验证项,不创造风格缺陷。

验收与交付

审查结果至少让另一作者能够找到问题并实施修正。工具输出作为证据的一部分,不能代替语义与读者任务判断。

有修复授权时完成相关修改和复查,只列剩余问题;审查-only 时保留工作区内容,提供报告。示范见EX-04。

任务入口