产品类型实践 · 文档规范 · 2026-08-20

文档规范实践
G0 文档体系 vs IEEE 830 / 1016 / 829

小八弟 · 网站/应用类软件产品 · 分类实践篇(参照 IEEE 文档三件套 / ADR)

← 返回 文档规范板块
一句话导读
我们的 G0 前置文件(需求规格 / 架构设计 / 测试规划 / 遵从声明)与 IEEE 的文档三件套(830 需求 / 1016 架构 / 829 测试)一一对应,还多了「遵从声明 + 平台引用确认」这类工程化补充。这篇对照拆解:G0 哪里比三件套强、哪里还缺。

一、现状:G0 四件 vs IEEE 三件(🟢 本机实测)

我们(G0 前置文件)对应 IEEE / ISO差异
需求规格(功能/非功能 + P1/P2/P3 平台引用确认)IEEE 830 / ISO 29148 需求规格我们多了「P1/P2/P3 平台引用确认」(谁在用、依赖什么平台),更贴近工程落地
架构设计(目录/数据流/生成器方案)IEEE 1016 架构描述 / ISO 42010我们用「视图」精神但未显式命名视角;架构决策另走 ADR
测试规划(用例 + 预期结果 + 门禁对照)IEEE 829 测试文档我们的测试规划与五连门禁绑定,测试=门禁+人工核验
遵从声明(声明按规范执行 + 平台引用)(无直接对应,接近合规声明)这是我们的特色:无遵从声明④不得开工——把「承诺」文档化

二、经验教训

教训 1:文档要「为决策服务」,不是「为存档服务」
早期 G0 文档容易写成流水账。IEEE 830 的核心提醒是「每条需求可验证」——我们现在写需求规格会自问:这条能不能被门禁/测试验到?验不到的需求别写。
教训 2:架构文档的「决策」比「图」值钱
IEEE 1016 强调架构是一组设计决策。我们吃过亏:架构图好看但「为什么选这个方案」没记录,半年后自己都说不清。现在架构设计里必须写「决策 + 备选方案」,配合 ADR 机制留痕
教训 3:测试规划的「可追溯」要到需求级
IEEE 829 的用例链(计划→设计→用例→报告)我们覆盖了前 3 层,但「用例 ↔ 需求」的追溯矩阵一度缺失——这也是调研报告建议⑤「G0→门禁追溯矩阵」要补的。受监管行业(IEC 62304)把双向可追溯当硬要求,我们正往这个方向靠。
教训 4:ADR 是文档体系的「粘合剂」
没有 ADR 时,架构变更散落在日志里找不到。8/20 落地 docs/决策记录/(ADR-001~005)后,关键决策(认证方案、主站迁移、双根同步)都有了「背景-决策-后果-备选」的记录——这是对 IEEE 文档体系的最佳实践补充。

三、行业现状对照

四、下一步改进

  1. 补 G0→门禁追溯矩阵:遵从声明加「对应门禁」列,让需求可追溯落到门禁;
  2. 架构视图命名:架构设计里显式标注「逻辑视图 / 部署视图 / 数据视图」,向 1016/42010 对齐;
  3. ADR 常态化:把「关键变更必写 ADR」写进管理办法,形成习惯。
⚠️ 实践篇(🟢 现状为本机实测 / 行业现状为 🟡 公开资料归纳),标准对照以官方文本为准。