# 产品文档写作约束 本文档定义 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 不复制通用规则全文 - 通用规则变更必须记录影响范围 先做到这些，就能避免大部分产品矩阵文档失控问题。