文档写作检查清单

1. 开写前

• 我是否先判断了文档类型：控制平面、设计、执行、规则、研究还是机器合同
• 我是否知道本文的目标读者是谁
• 我是否知道本文的 canonical 作用是什么
• 我是否知道本文不负责什么
• 我是否知道需要和哪些现有文档对齐

2. 结构检查

• 是否先有清晰骨架，再填内容
• 顶部是否有摘要、定位或项目说明入口
• 中长文是否有目录
• 标题层级是否稳定
• 同级章节是否同粒度
• 是否存在“杂项”“补充说明”一类低信息量标题

3. 事实检查

• 当前事实是否放在前面
• 关键 URL、路径、服务名、脚本名是否明确
• 历史别名是否显式标为 legacy / compatibility
• 是否把猜测写成了事实
• 是否把目标态写成了当前状态

4. 分层检查

• 事实层、约束层、策略层、路线图层是否明确分开
• 面向人和面向机器的内容是否分开
• 主线内容和附录内容是否分开

5. 论文级质量检查

• 术语是否先定义后使用
• 每章是否都在回答一个明确问题
• 结论是否能追溯到事实、结构、代码边界或验证方式
• 引用是否区分官方来源、代码来源、运行验证来源和推断来源
• 图片是否有图题、图意说明和来源标注
• 公式是否先定义符号，再给公式与自然语言解释
• 是否存在大段空泛 prose
• 是否有足够的表格、链路图、矩阵或模板来承载结构化信息

6. README / project.json 配对检查

• README.md 是否承担人类控制平面手册职责
• project.json 是否承担机器合同职责
• README 顶部事实是否与 project.json 对齐
• verificationScripts、deploymentScripts、入口 URL、服务名是否一致

7. 可执行性检查

• 读者是否能凭这份文档知道下一步怎么做
• 规则文档是否给出判断标准
• 调试文档是否给出排障顺序
• 迁移文档是否给出目标态、步骤、风险与回滚
• 研究文档是否给出对比标准与结论
• 如果是博客，是否在保持叙事可读性的同时仍保留术语定义、结构分层、证据基础与明确结论

8. 风格检查

• 语言是否精确、克制、事实态
• 版式是否适合长时间阅读
• 标题、正文、代码、引用块层级是否稳定
• 是否有口语化含糊词
• 是否有重复结论
• 文件名是否足够表达用途
• 文档是否具有跨项目复用价值