9.7 KiB
9.7 KiB
产品文档写作约束
本文档定义 IoT 产品定义文档的写作边界。它回答三个问题：
- 每一层应该写什么
- 每一层不应该写什么
- 文档之间应该如何引用、继承和维护
这套约束适用于通用规则、单品 PDD、角色视图和文档协作规范。
总体写作原则
只写产品定义，不写技术实现
产品文档描述用户体验、产品规则、业务边界、异常处理和跨团队协作口径。
产品文档不展开具体技术实现方案。
推荐写法：
设备离线后，App 应在设备卡片展示离线状态，并提示用户检查电源与网络。
不推荐写法：
设备端每 30 秒上报一次心跳，云端超过 90 秒未收到 MQTT 消息后将设备标记为离线。
如果某条规则必须依赖技术条件，也只描述产品侧可感知的条件和结果。
一个事实只写一次
通用规则只允许在通用规则层定义。单品 PDD、角色视图和其他文档只能引用，不应复制全文。
推荐写法：
本产品配网超时体验遵循 [通用配网体验规则](../domain/networking.md#配网超时)。
引用规则：NET-PAIRING-TIMEOUT
不推荐写法：
配网超时为 90 秒。超时后 App 提示用户检查 Wi-Fi 密码、网络环境和设备状态。
如果这段内容已经属于通用规则，就不应在单品 PDD 中重复维护。
先判断归属，再写内容
写任何规则前，先判断它属于哪一层。
- 多个设备都会用到：写入通用规则层
- 只属于某一款设备：写入单品定义层
- 只是给某个角色阅读：写入交付视图层
- 是文档维护方式：写入协作管理层
不要因为某个内容当前只被一个设备使用，就立即写进单品 PDD。如果它未来大概率会复用，应优先放入通用规则层。
允许差异，但必须说明原因
单品可以偏离通用规则，但必须说明差异原因。
差异原因通常来自：
- 硬件形态限制
- 安装环境限制
- 目标用户差异
- 使用场景差异
- 法规或认证要求
- 成本、续航、体积等产品约束
推荐写法：
本产品不使用声音告警。
差异原因：设备主要安装在卧室，声音告警可能打扰用户休息。
替代体验：通过 App 推送和红灯慢闪提示异常。
一、通用规则层
应该写什么
通用规则层写跨设备复用的产品规则，是产品定义体系的唯一事实来源。
应该写：
- 设备生命周期状态
- HMI 指示灯、按键、蜂鸣器等交互语言
- 通用配网流程和异常体验
- 绑定、解绑、分享、迁移规则
- 通用告警分级和提示口径
- App 通用状态展示规则
- OTA 体验规则
- 数据采集口径
- 权限和安全相关的产品规则
- 跨设备复用的术语定义
不应该写什么
通用规则层不写单个设备的专属定义。
不应该写：
- 某一款设备的产品定位
- 某一款设备的目标用户画像
- 某一款设备的外观、尺寸、材质
- 某一款设备的独有安装方式
- 某一款设备的独有卖点
- 某一款设备的项目排期
- 某一款设备的研发实现方案
- 某一款设备的临时决策过程
写作要求
每条通用规则应包含：
- 规则名称
- 规则编号
- 适用范围
- 产品定义
- 用户感知
- 触发条件
- 例外情况
- 被引用产品
- 版本记录
建议结构：
### 配网超时
规则编号：NET-PAIRING-TIMEOUT
适用范围：所有需要 App 配网的设备。
产品定义：设备进入配网流程后，如果在规定时间内未完成绑定，系统应判定为配网超时。
用户感知：App 展示配网失败，并提供重新配网入口。
触发条件：用户发起配网后，设备未在规定时间内完成绑定。
例外情况：无 App 配网能力的设备不适用。
被引用产品：
- sensor-a
- gateway-a
二、单品定义层
应该写什么
单品定义层写具体设备的 PDD，描述这款产品本身。
应该写：
- 产品定位
- 目标用户
- 核心场景
- 产品价值
- 功能范围
- 不做什么
- 设备形态
- 安装方式
- 供电方式
- 续航目标
- 环境约束
- 与通用规则的引用关系
- 本产品独有规则
- 本产品对通用规则的差异说明
- 异常体验和边界条件
- 版本记录
不应该写什么
单品定义层不重复写通用规则，不展开技术方案。
不应该写：
- 已在通用规则层定义过的完整规则
- 其他设备的产品定义
- 技术协议字段
- 数据库表结构
- 接口请求和响应
- 固件任务拆分
- 研发排期细节
- 测试用例全文
- 运营话术全文
写作要求
单品 PDD 应明确区分三类内容：
- 引用规则：来自通用规则层
- 本品规则：只属于当前设备
- 差异规则：对通用规则的例外或微调
建议结构：
## 引用的通用规则
- [HMI 全局交互字典](../../domain/hmi-dictionary.md)
- [通用配网体验规则](../../domain/networking.md)
- [设备生命周期状态](../../domain/device-lifecycle.md)
## 本产品独有规则
本产品支持磁吸安装，用户可在金属表面直接固定设备。
## 通用规则差异
通用规则：HMI-LIGHT-RED-FAST
差异说明：本产品无红色指示灯，致命故障改为 App 强提醒 + 蜂鸣器连续 3 声。
差异原因：设备仅配置单色白灯，无法表达红灯状态。
三、协作管理层
应该写什么
协作管理层写文档体系如何被维护。
应该写：
- 文档命名规则
- 目录结构规则
- Markdown 引用规则
- 规则编号规则
- Git 分支规则
- 提交信息规则
- PR 评审要求
- 版本标签规则
- 变更记录格式
- 废弃规则处理方式
- 文档责任人机制
不应该写什么
协作管理层不写具体产品内容。
不应该写：
- 单个设备的功能定义
- 单个设备的用户场景
- 单个设备的物理约束
- 某条具体 HMI 规则的完整定义
- 某条具体告警规则的完整定义
- 项目会议纪要全文
写作要求
协作管理层应写成可执行的规则，而不是泛泛建议。
推荐写法：
单品 PDD 引用通用规则时，必须同时包含 Markdown 链接和规则编号。
不推荐写法：
建议大家尽量保持文档引用清晰。
四、交付视图层
应该写什么
交付视图层写不同角色的阅读入口。它从已有文档中组织信息，而不是创造新的产品事实。
应该写：
- 硬件团队关注的产品约束入口
- 设计团队关注的交互规则入口
- 研发团队关注的状态和边界规则入口
- 运营团队关注的用户场景和告警解释入口
- 管理团队关注的范围、风险和版本入口
不应该写什么
交付视图层不应成为新的事实来源。
不应该写：
- 未在通用规则层或单品定义层出现的新规则
- 与原始文档不一致的改写
- 为了阅读方便而复制大段原文
- 绕过 PDD 的临时口径
- 只存在于视图层的产品承诺
写作要求
交付视图层应以链接和摘要为主。
推荐写法：
## 设计团队入口
- 配网流程：[通用配网体验规则](../domain/networking.md)
- 指示灯语言：[HMI 全局交互字典](../domain/hmi-dictionary.md)
- sensor-a 差异规则：[sensor-a PDD](../products/sensor-a/pdd.md#通用规则差异)
不推荐写法：
## 设计团队入口
这里重新完整描述一遍配网流程、指示灯规则和 sensor-a 的所有差异。
内容归属判断表
| 内容 | 应放层级 | 原因 |
|---|---|---|
| 蓝灯慢闪代表配网中 | 通用规则层 | 多设备复用的 HMI 语言 |
| 某设备没有蓝灯 | 单品定义层 | 单品硬件差异 |
| 配网超时时间 | 通用规则层 | 跨设备一致体验 |
| 某设备配网超时后只震动不亮灯 | 单品定义层 | 单品差异 |
| 文档必须使用相对链接 | 协作管理层 | 文档维护规则 |
| 给设计团队的阅读入口 | 交付视图层 | 面向角色的信息组织 |
| 产品卖点介绍 | 单品定义层 | 单个产品的市场与用户价值 |
| 告警分级标准 | 通用规则层 | 跨设备复用规则 |
| 某设备不支持 OTA | 单品定义层 | 单品能力限制 |
| Git tag 命名方式 | 协作管理层 | 版本管理规则 |
文档写作检查清单
提交任何产品文档前，应检查：
- 是否写的是产品定义，而不是技术实现
- 是否存在重复定义通用规则
- 是否明确了内容所属层级
- 是否为通用规则提供了规则编号
- 是否使用了相对链接
- 是否说明了单品差异原因
- 是否避免在视图层创造新规则
- 是否记录了重要变更
- 是否能让对应团队直接理解并执行
禁止事项
以下行为会破坏产品文档体系，应避免：
- 把同一条规则复制到多个 PDD 中
- 在角色视图中偷偷新增产品规则
- 在单品 PDD 中写大量接口、协议、数据库、固件任务内容
- 修改通用规则但不说明影响范围
- 删除规则但不说明替代方案
- 使用无法迁移的本地绝对路径作为文档链接
- 使用“见群聊”“见会议纪要”作为规则来源
- 用口头约定替代文档规则
最小落地约束
如果团队刚开始执行，至少遵守以下规则：
- 所有通用规则放在
docs/domain/ - 所有单品 PDD 放在
docs/products/ - 所有文档使用 Markdown
- 所有跨文档引用使用相对链接
- 所有通用规则必须有规则编号
- 单品 PDD 不复制通用规则全文
- 通用规则变更必须记录影响范围
先做到这些，就能避免大部分产品矩阵文档失控问题。