文档规范

文档是交付的一部分，不是可选附件。
好文档回答三问：是什么、怎么跑、为什么这样设计。

1. 文档要回答的三问

1. 这是什么？ 模块职责、边界、不负责什么
2. 怎么跑起来？ 环境、依赖、配置、主路径、常见坑
3. 为什么这样设计？ 关键取舍，避免后人「好心重构」踩雷

2. 分层与粒度

类型	读者	内容重点
操作说明	业务/运营	任务路径、截图可少但步骤要全
接口文档	调用方	契约、示例、错误码
部署运维	实施/运维	环境、发布、回滚、监控
设计说明	研发	边界、数据流、状态机、取舍
复盘	团队	时间线、根因、改进项

不必每篇都写很长；正确且可执行优先于漂亮。

3. 版本同步

• 文档标注适用版本/日期
• 接口/配置变更合并时，同步改文档
• 废弃内容标明「已废弃」与替代，不直接删到让人迷路
• 错误文档比没文档更危险——发现过期立刻改或下线

4. 写作风格

• 步骤可复现：别人跟着做能跑通
• 写限制与不适用场景
• 关键路径给示例（请求/命令/配置片段）
• 少空话；术语首次出现可一句话解释

5. 敏感信息

• 文档默认不含生产密钥与真实隐私数据
• 示例用脱敏/假数据
• 权限申请流程可写，密钥值不写

6. 文档 DoD

• 与当前实现一致
• 主路径可按文档走通
• 已知坑有记录
• 联系人/升级方式可知（或指向交接文档）

详见 完成定义 与 交接清单。

本站教程类文档（Go / STM32）也尽量遵守上述原则：可复现、写限制、留后路。