Fluxon Docs

开发者 - 3 - 文档写作规约

11 min read

本文定义 Fluxon 仓库内用户文档、开发文档和设计文档的写法约束。目标只有两个：

  • 让读者能在最短时间内抓住稳定结论。
  • 让文档和代码、公开接口、实际行为保持一致。

1. 通用规则

  • 先写结论，再写展开。读者应在开头 30 秒内知道“这篇文档在回答什么问题”。
  • 优先使用工程上自然的术语，少用自造概念。除非真的必要，不要写“根对象”“第一层分支”“authority object”这类词。
  • 面向读者写，不要把作者的思维过程原样摊开。删除“这一节不讨论什么”“这个分支为什么属于上一层”这类模板套话。
  • 如果一段文字可以改成表格、列表或图，就不要硬写成长段线性描述。
  • 文档里的接口名、类型签名、返回值语义必须和代码一致；不允许文档里讲一套、代码里做另一套。
  • 示例和快速开始必须走稳定公共接口，不要把内部兼容层、探测逻辑、历史写法暴露给用户。
  • 性能结论必须绑定条件。写清测试场景、对比对象和结论边界，避免抽象地写“性能更好”。
  • 规约要写成可复用的方法，而不是当前案例的复述。具体技术事实、事故教训、性能数字更适合作为示例、反例或 review checklist。
  • 对行为、所有权、性能这类结论，必须先定义观察范围：在什么抽象层上讨论、结论覆盖到哪一步、前提是什么、不包含什么。
  • 不要把某个局部事实直接抬升成系统级结论；如果要上升到更高层，必须按同一抽象层把完整路径补齐。
  • 如果开头枚举了痛点、目标、评估维度或问题清单，后文要按同一组轴逐项回应。不要开头按 A/B/C 提问，正文却切到另一套分类。
  • 同一个概念在一篇文档和同一套文档里，只保留一个规范名称、拼写和大小写；角色名、组件名、缩写都一样。
  • 可复用的仓库级实现规约应写入中英文同步的开发者文档，并在 AGENTS.md 和 AGENTS_CN.md 的“规约索引”中各保留一条简明入口；不要把完整规约复制到索引中。

2. 设计文档

设计文档默认按 RFC/ADR 风格组织，优先使用下面这条主线：

  1. 背景与目标
  2. 非目标
  3. 核心模块或角色
  4. 架构图或时序图
  5. 按数据流或调用流展开详细设计
  6. 约束、不变量、失败条件
  7. 关键结论

设计文档尤其要遵守这些规则：

  • 跨语言边界、生命周期管理、异步时序、所有权转移这类内容，默认要配图。没有图时，读者很难稳定理解。
  • 优先按“数据怎么流动”来写，而不是按“作者脑中的树状结构”来写。
  • 明确区分公共接口、当前实现、专用优化路径。不要把通用契约和特化 fast path 混成一个结论。
  • 对容易被误解的结论，必须沿完整链路逐段核对，并保持抽象层一致：输入如何形成、边界如何穿过、下游如何消费、生命周期如何结束。
  • 如果有多个路径，例如 put pointer path 和 rpc_call(payload) bytes path，要并列比较，不要在正文里来回切换。
  • 如果某条路径只覆盖了系统中的一个局部步骤，要显式标出剩余步骤，不要让读者误以为整个语义操作都已经被同样优化。

3. 用户文档

  • 先给稳定用法，再给约束和常见坑。
  • 默认回答“怎么用”，不是“内部怎么实现”。
  • 命令、参数、返回对象、前置条件必须能直接照着执行。
  • 不要在用户文档里引入内部保留字段、临时适配层或只对当前实现细节成立的说法。
  • 如果接口有明确契约，例如 FlatDict、MemHolder、Future.wait()，文档必须直接使用这些契约，不要写“也许还能传别的类型试试”。
  • 在截图、GIF、终端输出或 Web UI 预览前，先写一句预期结果或成功判据，让读者先知道“接下来会看到什么”。

4. 开发文档

  • 只写维护者真正需要的信息：入口脚本、关键目录、产物、命令、重跑条件。
  • 对流程文档，优先写“命令 + 产物 + 什么时候需要重跑”。
  • 对代码导览文档，优先写“模块职责 + 调用边界 + 不变量”。
  • 不要把一次性排障记录、临时操作步骤、个人环境路径写进长期文档。

5. 表达约束

  • 少写空话，例如“增强可维护性”“提升可扩展性”。如果要写，就补上对象和机制。
  • 少写“不是……而是……”。只有在前文已经建立了两边的对比，并且这句对读者判断有直接帮助时才使用。
  • 少写过长段落。连续几百字的纯文字说明，通常都可以拆成图、表或列表。
  • 术语第一次出现时给出落点，例如对应的代码模块、结构体、公共类型或保留字段。
  • 对重要边界，优先用表格写“支持什么 / 不支持什么 / 为什么”。
  • 中文或中英混排文档中，中文与英文、中文与数字之间默认加一个半角空格；中文标点前后不要机械补空格。
  • 对命令、路径、端口号、配置键、类型名、接口名、第三方组件名等精确标识，使用反引号包裹。
  • 列表项如果同时包含核心判断和解释，优先写成“加粗结论：展开说明”，让读者能先扫到结论。
  • 英文列表标题保持词性平行；如果是在枚举痛点、能力或 trade-off，优先使用名词短语。
  • 英文文档优先采用业界自然术语和常见搭配，不要逐词翻译中文原句。
  • 技术缩写默认全大写，除非品牌、项目或公开接口本身另有固定写法。
  • Benchmark、性能对比和运行效果描述，优先使用客观工程措辞，例如“基本持平”“仍有进一步优化空间”，少用口语化判断。
  • 一句话如果同时承载多个动作、转折和结论，优先拆句，避免读者在长句里回溯主语和约束条件。

6. 示例与反例

下面这些明确只是示例和反例，不是规约本身；它们的作用是帮助识别规约为何重要：

  • 把“跨某一个语言边界不复制”误写成“整个调用链零拷贝”。
  • 把“单字段可借用”误写成“多段协议 payload 可直接零拷贝组装”。
  • 把“底层 buffer 可复用”误写成“上层对象构造没有成本”。
  • 把“数据面没有额外 memcpy”误写成“控制面、调度面、锁或 GIL 也没有成本”。

这些案例的共同问题不是技术点本身，而是：

  • 没有先定义结论的作用范围。
  • 混用了不同抽象层的事实。
  • 用局部观察代替了全链路论证。

7. 发布前检查

提交文档前至少检查这几项：

  • 开头是否已经说明本文目标和适用边界。
  • 文中的接口名、路径、类型名是否真实存在。
  • 是否混淆了公共接口和内部特化路径。
  • 是否把局部优化误写成全链路结论。
  • 是否遗漏了编码、拼接、materialize、锁、GIL 或下游重建等剩余成本。
  • 是否缺少能显著降低理解成本的图或表。
  • 是否存在明显模板腔、套话、术语不自然的问题。
  • 是否存在复制粘贴造成的重复段落、重复小节或残留草稿。
  • 中英文混排空格、反引号、术语拼写、大小写是否已经统一。
  • 顶部目录、锚点跳转、图片路径、外部链接是否都可正常访问。
  • 代码块是否声明了正确的语言类型，例如 bash、python、yaml。
  • 新增的仓库级实现规约是否已经同步加入 AGENTS.md 和 AGENTS_CN.md 的规约索引。