doc-writing:让人读懂结构,而不是复述实现
何时用
产出任何给人读的技术文本。句子层面另见 plain-language。
硬规则
- MUST 每份文档有一个确定功能(回答一个问题),不是信息聚合;写不出"这份文档回答什么"就不写。
- NEVER 两份文档相互重复或相互论证;同一事实一处定义,其他链接。
- MUST 形容词与程度词带证据(数字、引用、对比),否则删。
- NEVER 写自我论证("我证明这个功能没必要加");结论直接写,理由只在读者必须知道时写一句。
- MUST 结构、接口、数据流优先于实现步骤;读者先看懂"是什么、怎么用、依赖什么"。
- MUST 改文档做最小有效修改:只动需要改的句子,不顺手重写。
- MUST 新内容插在最相关的已有内容相邻处,不新开孤立章节。
- MUST 项目 README 有「结构」一节:模块、各自职责、哪些是 core 值得完全理解、哪些是 commodity 只需契约;结构变时同步。
审问清单
- 这份文档回答的唯一问题是什么?标题体现了吗?
- 哪句话在别的文档已经有了?
- 哪个形容词没有证据?
- 哪段是在为自己辩护而不是告诉读者事实?
- 读者读完能画出结构图、知道怎么调用吗?
- 这次修改动了几处?每处都必要吗?
反模式
- 错误:"本模块采用了高性能、可扩展的架构设计。" → 正确:"单实例 2k req/s(压测见 §5);水平扩展靠无状态 worker。"
- 错误:README 里再解释一遍设计文档的取舍。→ 正确:README 一句链接到设计文档对应节。
- 错误:加一个配置项,把整个配置章节重排。→ 正确:在相邻配置项后插一行。
输出要求
文档开头一句说明它回答什么;改动时列出修改位置。