docs: 建立最小交付文档体系 (#11)

2026-08-10 14:25:34 +08:00
parent 4e9f2e1380
commit 3474870499
8 changed files with 285 additions and 13 deletions
@@ -0,0 +1,80 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Delivery-Documentation-Guide
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Delivery-Documentation-Guide.-
+wiki_revision: d9de4f8d8abc40630069c67948ca2a5086f90e70
+synchronized_at: 2026-08-10T06:23:38Z
+<!-- gitea-wiki-mirror:end -->
+
+# 交付文档指南
+
+## 本页用途
+
+本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。
+
+最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。
+
+## 什么时候需要交付文档
+
+出现以下任一情况时，应在单元任务工单中评估并更新交付文档：
+
+- 新增或改变用户可见功能、操作步骤、界面、权限或限制；
+- 改变安装、配置、部署、备份、恢复、监控或升级方法；
+- 改变外部 API、数据格式、集成条件或兼容范围；
+- 改变常见故障的识别、处理或支持方式；
+- 发布新版本或交付客户验收。
+
+纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。
+
+## 受众与文档选择
+
+| 交付对象 | 典型文档 | 需要回答的问题 |
+|---|---|---|
+| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 |
+| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 |
+| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 |
+| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 |
+| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 |
+| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 |
+
+一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。
+
+## 内部文档与交付文档边界
+
+交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。
+
+面向客户或公开的文档不得包含：
+
+- 内部工单链接、聊天记录、内部决策过程或任务归档；
+- 内部网络地址、仓库路径、无必要的源码模块名和调试细节；
+- 密码、令牌、Cookie、私钥、个人数据或生产数据；
+- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段；
+- 未承诺的路线图、期限和功能。
+
+交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。
+
+## 编写和维护流程
+
+1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。
+2. 使用[岗位文档模板](Audience-Document-Template.-)按需创建文档，不创建没有明确读者的空页面。
+3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。
+4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。
+5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。
+6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。
+7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 `docs/` 镜像。
+
+具体项目创建的岗位文档应增加到 `wiki-docs.json` 的显式映射中。本模板自身的指南和模板镜像位于 `docs/delivery/`。
+
+## 最小验收清单
+
+- [ ] 文档有明确受众、适用版本、可见范围和负责人。
+- [ ] 前置条件、操作步骤和预期结果完整且可以对应。
+- [ ] 常见失败、恢复方法、安全提示和已知限制已说明。
+- [ ] 关键步骤由目标岗位视角验证，或明确记录未验证项。
+- [ ] 外部版本不含内部链接、敏感数据和无关实现细节。
+- [ ] 本次功能变化涉及的交付文档已更新并与版本一致。
+- [ ] Wiki 已读取确认，本地镜像检查一致。
+
+## 不在本页解决的内容
+
+开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。
@@ -0,0 +1,96 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Audience-Document-Template
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Audience-Document-Template.-
+wiki_revision: 7a8f38df566fe639094497c9692e0559c9c080e6
+synchronized_at: 2026-08-10T06:23:41Z
+<!-- gitea-wiki-mirror:end -->
+
+# 岗位文档模板
+
+> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。
+
+## 文档信息
+
+| 字段 | 内容 |
+|---|---|
+| 文档名称 | |
+| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 |
+| 适用版本 | |
+| 最后验证日期 | YYYY-MM-DD |
+| 负责人 | |
+| 可见范围 | 内部 / 指定客户 / 公开 |
+| 相关产品或模块 | |
+
+## 目的与适用范围
+
+说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。
+
+## 前置条件
+
+- 所需权限：
+- 所需环境或设备：
+- 已完成的准备：
+- 需要提前获得的信息：
+
+不得在这里填写真实密码、令牌、个人数据或生产数据。
+
+## 操作步骤
+
+### 任务一：<明确的操作目标>
+
+1. <执行动作>
+2. <执行动作>
+3. <执行动作>
+
+**预期结果**：<读者可以观察到的成功结果>
+
+**失败时**：<先检查什么；何时停止并联系支持>
+
+每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。
+
+## 常见错误与恢复
+
+| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 |
+|---|---|---|---|
+| | | | |
+
+只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。
+
+## 安全与权限
+
+- 本岗位允许执行的操作：
+- 明确禁止或需要审批的操作：
+- 敏感信息处理规则：
+- 数据、日志和截图脱敏要求：
+- 删除、发布、迁移或其他高风险操作的确认要求：
+
+## 已知限制
+
+- 支持的环境和版本：
+- 当前不支持的场景：
+- 兼容性限制：
+- 未验证的环境或步骤：
+
+## 支持与升级处理
+
+- 支持渠道：
+- 服务时间或响应约定：
+- 联系支持前需要收集的信息：
+- 不得提交的信息：
+- 需要升级到下一岗位或负责人的条件：
+
+## 版本记录
+
+| 日期 | 适用版本 | 变更内容 | 验证人 |
+|---|---|---|---|
+| | | | |
+
+## 交付前检查
+
+- [ ] 目标岗位能够理解术语和步骤。
+- [ ] 前置条件、步骤与预期结果一一对应。
+- [ ] 关键流程已按目标岗位视角验证。
+- [ ] 常见错误、恢复方法和升级条件清楚。
+- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。
+- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。