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