工程文档写作总规范

1. 目标

这份规范用于约束我以后为任何项目撰写文档时的默认写法。

目标不是把文档写得“像作文”，而是尽量靠近论文级别的严密性、层次感、定义清晰度、证据意识和结构可复用性，同时保留工程文档必须有的可执行性。

这份规范适用于：

• README.md
• 系统设计文档
• 架构说明
• 实施手册
• 运维手册
• 调试手册
• 迁移方案
• 验收文档
• 研究综述
• 技术博客 / 深度博客长文
• 规范与规则文档
• project.json 一类机器可读合同

2. 总原则

以后写文档，默认遵守下面十条总原则：

2.1 真相优先

• 先写当前已确认事实，再写目标态、建议或路线图。
• 不把未落地内容写成既成事实。
• 不把历史路径、兼容层、试验层伪装成当前主路径。

2.2 定义优先

• 重要名词先定义，再使用。
• 缩写、别名、兼容命名都要说明主名与从名关系。
• 如果一个词在工程里可能歧义，必须消歧。

2.3 结构优先

• 先有目录骨架，再填内容。
• 一章只解决一类问题。
• 同级标题必须同粒度，不要一边讲系统、一边讲函数。

2.4 分层优先

• 事实、约束、策略、实现、历史、路线图必须分层。
• 面向人和面向机器的内容必须分层。
• 主叙述和附录必须分层。

2.5 证据优先

• 时间敏感、路径敏感、接口敏感内容尽量给出明确路径、URL、字段、服务名、脚本名。
• 结论要么来自现状，要么来自可验证推导；推导要标出这是推导。
• 不靠模糊语气替代证据。

2.6 可检索优先

• 标题要让人一眼知道本节解决什么问题。
• 文件名要表达用途，避免 final、misc、notes2 之类名称。
• 同类信息尽量固定写在固定章节。

2.7 可执行优先

• 设计文档不只是解释，还要能指导后续实现、验证、排障或维护。
• 规则文档不只是价值观，要能落到判断标准、约束、步骤或模板。

2.8 精确优先

• 用具体名词替代泛泛概括。
• 用明确路径、端口、边界、字段替代“系统那边”“服务那里”。
• 用定量结构替代空泛总结。

2.9 克制优先

• 不堆无用修辞。
• 不堆重复结论。
• 不把一句话能说清的事写成三段空话。

2.10 复用优先

• 文档结构要能被后续项目复用。
• 重复出现的结构要抽象成模板。
• 规则要能迁移，而不是只绑定单一项目。

3. 接近论文水准的写法要求

工程文档不需要模仿学术论文的语言腔调，但要尽量借用论文好的部分。

以后默认吸收下面这些“论文式优点”：

3.1 摘要意识

• 文档前部要有压缩版结论区。
• 让读者先知道本文讲什么、适合谁、边界在哪。
• 不要让读者翻十页才知道文档主题。

3.2 术语意识

• 重要概念建立术语表或名词约定。
• 同一实体只保留一个 canonical 名称。
• 历史别名必须标明是 alias 或 legacy。

3.3 命题意识

• 每一章都应隐含回答一个问题。
• 每段最好围绕一个明确命题展开，而不是自由散射。

3.4 论证意识

• 结论要能追溯到事实、结构图、代码边界、脚本或配置。
• 如果是建议、推导、目标态，要显式标注层级。

3.5 分节意识

• 标题层级应稳定、可预测、可跳读。
• 章节编号要体现逻辑树，不只是装饰。

3.6 附录意识

• 主线保留必要事实与结论。
• 扩展背景、样例、长表、历史材料放附录。

3.7 目录意识

• 中长文必须提供目录或可跳转提纲。
• 目录不是装饰，而是信息定位器，必须反映真实章节结构。
• 目录应服务于跳读、引用和后续维护。

3.8 引用意识

• 引用要区分事实来源、推导来源和示例来源。
• 重要结论必须能追溯到来源，不允许只给无出处判断。
• 时间敏感结论要标时间或版本范围。

3.9 图表与公式意识

• 图片、图表、公式都必须服务于解释，不是装饰。
• 每个图表和公式都要有编号、标题或至少有明确的上下文引导。
• 没有解释的图、没有定义的符号、没有来源的图表都视为不完整。

4. 文档类型分类法

以后先判断文档类型，再决定结构。

4.1 控制平面文档

用于回答“系统现在是什么、怎么进、边界在哪、如何验证”。

典型文件：

• README.md
• 运维总手册
• 项目总览

4.2 设计文档

用于回答“为什么这样设计、结构如何分层、模块职责怎样切分”。

典型文件：

• 架构设计
• 模块设计
• 接口设计

4.3 执行文档

用于回答“怎么部署、怎么迁移、怎么排障、怎么验收”。

典型文件：

• 发布手册
• 排障手册
• 迁移方案
• 验收方案

4.4 规则文档

用于回答“什么可以做、什么不可以做、判断标准是什么”。

典型文件：

• 代码规则
• 文档规则
• 安全/风控规则

4.5 研究文档

用于回答“现状如何、方案如何比较、推荐结论是什么、证据是什么”。

典型文件：

• 方案调研
• 技术对比
• 决策记录

4.5a 技术博客 / 深度博客文档

用于回答“如何把复杂主题讲清楚给外部读者，同时保持工程严密性、证据意识和可复用结构”。

典型文件：

• 技术博客
• 系统复盘长文
• 深度实现解析
• 工程经验总结

4.6 机器合同文档

用于回答“工具该读什么、路径在哪、脚本是什么、入口是什么”。

典型文件：

• project.json
• schema 合同
• manifest

5. 通用结构模板

除非文档类型非常特殊，否则以后优先复用这套通用骨架：

frontmatter
标题
定位说明
摘要 / 目标
读者与适用范围
术语或前置约定
主体分层
验证 / 使用 / 维护
附录 / 参考 / 历史

更细化地说：

5.1 frontmatter

至少考虑：

• title
• status
• owner 或 scope
• canonical 或 source

5.2 标题区

• 文件名表达用途
• 标题表达对象
• 副标题表达文档类型

5.3 定位区

开头用 2~4 句说明：

• 这是什么文档
• 谁应该读
• 和其他文档冲突时谁优先
• 本文不负责什么

5.4 摘要区

用最短篇幅说清：

• 系统对象
• 当前结论
• 使用入口
• 适用边界

5.5 主体分层

主体按以下层次拆分最稳定：

• 当前事实
• 约束与不变量
• 策略与执行顺序
• 设计与模块划分
• 实施与验证
• 路线图与未来工作
• 附录与历史

5.6 目录规范

以后默认目录规则如下：

• 短文小于约 1200 中文字时，可不单列目录，但标题层级仍要稳定。
• 中长文、综述、架构文档、博客长文、手册类文档默认必须有目录。
• 目录放在摘要与前置说明之后、正文主体之前最稳。
• 目录层级通常展示到三级标题；超过三级只在必要时展开。
• 目录名称优先用 目录、Contents 或项目既有 canonical 名称，不用花哨命名。

5.7 引用与参考规范

以后默认把引用分为四类：

1. 规范/官方来源
2. 代码/仓库来源
3. 运行验证/实验来源
4. 推断/经验来源

推荐标注方式：

• 行文内短引用：[来源: xxx]
• 章节末参考：参考来源
• 长文末统一参考区：参考与附录

标注要求：

• 官方文档写清文档名、版本或访问时间
• 代码来源写清仓库/文件/模块
• 运行验证写清时间、环境、命令或验证方式
• 推断必须明确标注“这是推断”

5.8 图片、图表与示意图规范

以后默认图片处理规则如下：

• 先判断这张图是不是必要；能用表格或列表讲清的，不强制画图。
• 架构、链路、状态迁移、对比矩阵优先用 text 图、表格或结构图。
• 需要截图时，必须确保截图能证明目标结论，而不是只展示漂亮界面。
• 每张图至少应有：
  • 图编号，如 图 1
  • 图标题
  • 一句图意说明
  • 若非原创，则给出来源

图片获取 / 生成 / 标注规则：

• 运行截图：来自本地验证、浏览器验证或系统界面，标注环境与时间更佳。
• 架构图：优先根据当前真相手工抽象生成，不直接拿营销图充数。
• 外部图片：优先使用可引用来源，并标注原始出处。
• AI 生成图：必须明确标注“AI 生成示意图”，不能伪装成真实运行证据。

5.9 公式规范

以后只有在公式比自然语言更清晰时才写公式。

适用场景：

• 成本计算
• 评分函数
• 路由选择函数
• 预算分配
• 概率或统计定义
• 复杂指标定义

规则：

• 先定义符号，再给公式。
• 公式后要用自然语言解释含义。
• 变量表最好单列。
• 公式编号只在长文、综述、研究文档、设计文档中启用。

Markdown / 文本环境推荐写法：

Score = alpha * Quality + beta * Cost + gamma * Stability

或在支持数学渲染的环境中使用：

S = \alpha Q + \beta C + \gamma T

并配套变量表：

5.10 版式与视觉样式规范

以后默认采用“朴素、清晰、可长读”的版式规范，不追求花哨。

语义层级优先于固定样式，但如果文档会导出为网页、PDF 或博客，默认样式建议如下：

• H1：28-32px，粗体，页面唯一
• H2：22-26px，粗体，章节级
• H3：18-20px，半粗体，小节级
• H4：16-18px，半粗体，只在必要时使用
• 正文：15-17px
• 行高：1.6-1.8
• 段前后距：保持稳定，不要忽大忽小
• 代码与表格字体：等宽，约正文 0.95em
• 引用块：比正文略小或同级，但视觉上要与正文分离

风格约束：

• 颜色以高可读、低干扰为主
• 长文不使用花哨背景
• 重点靠层级、留白、粗细和结构表达，不靠炫彩
• 图片宽度、表格宽度、代码块宽度要避免破坏阅读节奏

6. 各类文档的推荐结构

6.1 README / 总手册

优先采用：

• 项目说明入口
• Truth Layer
• Constraint Layer
• Strategy Layer
• 结构与职责
• 运维与验证
• 路线图
• 附录

6.2 架构设计文档

优先采用：

• 背景与目标
• 非目标
• 术语约定
• 架构总图
• 分层设计
• 数据流 / 请求流
• 模块职责
• 边界与不变量
• 验证与风险
• 开放问题

6.3 迁移方案

优先采用：

• 迁移目标
• 当前状态
• 目标状态
• 差异矩阵
• 步骤与阶段
• 风险与回滚
• 验证标准
• 剩余问题

6.4 调试 / 排障手册

优先采用：

• 现象定义
• 已确认事实
• 复现条件
• 分层排查顺序
• 常见根因
• 验证命令或证据
• 修复边界
• 相关附录

6.5 研究 / 调研文档

优先采用：

• 研究问题
• 评价标准
• 候选方案
• 对比矩阵
• 证据来源
• 结论
• 推荐方案
• 风险与保留意见

6.5a 技术博客 / 深度博客

优先采用：

• 文章摘要
• 目录
• 问题背景
• 为什么值得关心
• 核心概念与术语
• 系统或方案拆解
• 关键实现细节
• 对比与权衡
• 常见误区
• 结论与可执行建议

博客允许更强的叙事性，但不允许牺牲定义、分层、证据和结构完整性。

6.5b 博客与长文的配图 / 引用 / 公式要求

如果文档是博客或面向外部读者的深度长文，默认额外要求：

• 必须有目录
• 关键结论必须给出来源或证据类型
• 使用外部图片必须标注来源
• 使用运行截图必须说明这是截图证据还是示意图
• 使用公式必须同时给自然语言解释
• 若导出发布，样式必须保证长时间阅读舒适，不走夸张营销风

6.6 机器合同文档

优先采用：

• schema / 版本
• 身份字段
• 主入口
• 路径与服务
• 脚本索引
• workflow 索引
• compatibility / legacy
• 状态字段

7. 语言风格规范

7.1 语气

以后默认用：

• 中文叙述
• 工程语气
• 事实态
• 克制但不含糊

7.2 句式

推荐：

• “X 是唯一对外 canonical 入口”
• “Y 当前仅保留为 legacy alias”
• “本节只描述当前真实运行状态”
• “以下内容属于目标态，不代表当前已落地”

避免：

• “我觉得”
• “可能大概”
• “应该差不多”
• “看起来像是”

7.3 段落长度

• 一段通常只表达一个中心结论。
• 段落过长时要切成小节、表格或项目符号。

8. 表达形式选择规范

以后按信息类型选载体：

• 概念定义：短段落 + bullet
• 路径/字段索引：表格或 yaml/json
• 拓扑/链路：text 代码块箭头图
• 对比关系：矩阵表格
• 流程步骤：编号列表
• 规则/禁令：短 bullet
• 文献/来源：章节末引用或统一参考区
• 图片/截图：图题 + 图注 + 来源说明
• 公式：公式块 + 变量表 + 自然语言解释
• 大量例子：附录

9. 章节命名规范

• 标题必须说明对象与用途。
• 不要用“其他说明”“补充内容”“杂项”做正式章节名。
• 标题最好能被单独引用时仍自解释。

推荐：

• Real Runtime Topology
• Canonical Access Chain
• Verification Matrix
• Change Boundary Guardrail

不推荐：

• 说明
• 一些问题
• 更多内容
• 想法

10. 事实、约束、策略、路线图的隔离规范

以后严格隔离下面四层：

10.1 事实层

• 当前确实存在
• 当前可以验证
• 当前已生效

10.2 约束层

• 禁止事项
• 不变量
• 合法边界

10.3 策略层

• 建议顺序
• 默认执行协议
• 排障或实施方法

10.4 路线图层

• 尚未全部落地
• 未来阶段
• 目标态规划

任何文档都不要把这四层混成一锅。

11. 论文级质量检查点

以后我写完文档后，至少做下面检查：

• 是否在开头就说清了对象、范围、读者、用途
• 是否先给结论和真相，再给背景和延展
• 是否所有重要术语都已定义或消歧
• 是否区分了事实、推导、建议、目标态
• 是否所有关键路径、URL、文件、服务名都足够具体
• 是否提供了适当粒度的目录
• 是否重要结论都能追溯到来源或证据
• 是否图片、图表、公式都被正确解释和标注
• 是否存在“长而空”的段落
• 是否有结构复用价值，而不是只适合这一个项目
• 是否让第一次读这份文档的人也能快速定位主入口

12. 与 Token Pool 模式的关系

Token Pool 的 README.md + project.json 是本规范的一个高质量样本，但不是唯一适用对象。

以后默认关系如下：

• engineering-document-writing-standard.md：全局总规范
• token-pool-readme-projectjson-writing-pattern.md：README 与机器合同配对写法的专门拆解
• canonical-readme-template.md：可直接复用的 README 模板
• project-json-contract-template.json：可直接复用的机器合同模板
• document-writing-checklist.md：成文前后的统一检查表

13. 最终记忆锚点

以后写任何严肃工程文档，都先记住这句话：

先定义对象与范围，再给摘要与当前真相；
把事实、约束、策略、路线图分层；
让标题、表格、链路图、模板都服务于可检索与可执行；
语言保持事实态、结构化、精确、克制，并尽量达到论文级严密度。