软件开发文档管理规范

软 件 项 目 管 理 培 训 讲 座系 列 之 三 文 档 管 理 规 范2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 2内 容 提 要文 档 的 分 类 和 等 级文 档 管 理 的 原 则 和 方 法文 档 示 例 与 讨 论2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 3为 什 么 需 要 文 档 管 理 ？项 目 管 理 的 依 据了 解 进 度 、 分 析 问 题 ， 提 供 项 目 可 预 见 性工 作 交 流 的 凭 证口 说 无 凭 ， 立 字 为 据软 件 测 试 的 基 础没 有 文 档 ， 测 试 人 员 无 法 展 开 工 作培 训 用 户 的 参 考帮 助 外 界 人 员 了 解 项 目 内 幕技 术 支 持 的 帮 手帮 助 技 术 支 持 人 员 熟 悉 系 统 、 分 析 错 误 、 解 决 问 题记 录 历 史 的 必 须软 件 最 大 的 价 值 在 于 可 复 用 性2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 4为 什 么 需 要 文 档 管 理 ？2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 5编 写 文 档 的 基 本 思 路明 确 文 档 范 围 ， 避 免 空 泛 浮 躁大 而 全 的 文 档 是 没 有 用 的定 位 读 者 角 度 ， 防 止 对 牛 弹 琴以 读 者 能 够 理 解 作 为 编 写 文 档 的 标 准规 范 名 词 称 谓 ， 保 持 前 后 一 致统 一 的 名 词 和 称 谓 ， 会 降 低 文 档 的 歧 义 性注 重 版 本 控 制 ， 切 忌 顾 此 失 彼不 同 阶 段 的 文 档 记 录 了 项 目 开 发 的 完 整 过 程应 用 图 文 表 格 ， 保 证 内 容 清 晰简 洁 的 图 形 和 表 格 胜 过 前 言 万 语2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 6文 档 的 分 类 （ 1） 类 型 读 者 时 间 可 行 性 研 究 报 告 管 理 /研 发 人 员 可 行 性 研 究 与 计 划 阶 段 项 目 开 发 计 划 管 理 /研 发 人 员 可 行 性 研 究 、 需 求 分 析 阶 段设 需 求 规 格 说 明 书 研 发 人 员 需 求 分 析 阶 段计 功 能 规 格 说 明 书 研 发 人 员 需 求 分 析 阶 段开 概 要 设 计 说 明 书 研 发 /维 护 人 员 设 计 阶 段发 详 细 设 计 说 明 书 研 发 /维 护 人 员 设 计 阶 段类 数 据 库 设 计 说 明 书 研 发 /维 护 人 员 设 计 阶 段 模 块 开 发 卷 宗 管 理 /研 发 /维 护 人 员 实 现 、 测 试 阶 段 测 试 计 划 研 发 人 员 需 求 分 析 、 设 计 阶 段 测 试 分 析 报 告 研 发 /维 护 人 员 测 试 阶 段管 开 发 进 度 月 报 管 理 人 员 贯 穿 整 个 开 发 过 程理 项 目 开 发 总 结 管 理 人 员 测 试 阶 段类 职 责 定 义 管 理 人 员 可 行 性 研 究 与 计 划 阶 段 进 度 变 更 记 录 管 理 人 员 随 时 产 用 户 指 南 用 户 需 求 分 析 、 设 计 、 实 现 阶 段品 操 作 手 册 用 户 设 计 、 实 现 阶 段类 信 息 广 告 用 户 测 试 阶 段2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 7文 档 的 分 类 （ 2）文 件 阶 段 可 行 性 研 究与 计 划 阶 段 需 求 分析 阶 段 设 计阶 段 实 现阶 段 测 试阶 段 运 行 与维 护 阶 段数 据 需 求 说 明 书 项 目 开 发 计 划 软 件 需 求 说 明 书 数 据 需 求 说 明 书 测 试 计 划 概 要 设 计 说 明 书 详 细 设 计 说 明 书 数 据 库 设 计 说 明 书 模 块 开 发 卷 宗 用 户 手 册 操 作 手 册 测 试 分 析 报 告 开 发 进 度 月 报 项 目 开 发 总 结 2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 8文 档 的 分 类 （ 3）开 发 文 档可行性研究报告 项目开发计划 模块开发卷宗 测试分析报告需求规格说明书 功能规格说明书 概要设计说明书 详细设计说明书 数据库设计说明书 测试计划2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 9文 档 的 分 类 （ 4）产 品 文 档用 户 指 南 操 作 手 册 用 户 指 南产 品 手 册2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 10文 档 的 分 类 （ 5）管 理 文 档开 发 进 度 月 报 项 目 开 发 总 结 职 责 定 义进 度 变 更 记 录2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 11文 档 的 等 级 （ 1）确 定 文 档 质 量 等 级根 据 项 目 资 源 、 项 目 大 小 和 风 险 确 定 每 个 文 档的 格 式 及 详 细 程 度文 档 格 式 和 文 档 内 容 同 样 重 要必 须 保 证 文 档 的 质 量 ， 文 档 管 理 才 有 意 义 2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 12文 档 的 等 级 （ 2）文 档 按 照 质 量 可 划 分 为 四 个 等 级 ：最 低 限 度 文 档 （ 1级 文 档 ）适 合 开 发 工 作 量 低 于 一 个 人 月 的 开 发 者 自 用 程 序包 含 程 序 清 单 、 开 发 记 录 、 测 试 数 据 和 程 序 简 介内 部 文 档 （ 2级 文 档 ）适 合 于 没 有 与 其 他 用 户 共 享 资 源 的 专 用 程 序1级 文 档 内 容 ， 加 上 足 够 的 注 释 和 说 明2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 13文 档 的 等 级 （ 3）文 档 按 照 质 量 可 划 分 为 四 个 等 级 ：工 作 文 档 （ 3级 文 档 ）适 合 于 由 同 一 单 位 内 若 干 人 联 合 开 发 的 程 序 ， 或可 被 其 他 单 位 使 用 的 程 序正 式 文 档 （ 4级 文 档 ）适 合 那 些 要 正 式 发 行 供 普 遍 使 用 的 软 件 产 品关 键 性 程 序 或 具 有 重 复 管 理 应 用 性 质 （ 如 工 资 计算 ） 的 程 序 需 要 4级 文 档2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 14内 容 提 要文 档 的 分 类 和 等 级文 档 管 理 的 原 则 和 方 法文 档 示 例 与 讨 论2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 15文 档 管 理 的 基 本 原 则完 整 性 原 则项 目 文 档 集 应 覆 盖 软 件 开 发 的 完 整 流 程简 洁 性 原 则编 写 文 档 不 应 浪 费 过 多 的 时 间 和 经 历有 效 性 原 则文 档 必 须 能 够 起 到 辅 助 决 策 、 指 导 参 考 的 作 用延 续 性 原 则文 档 的 变 化 必 须 有 合 理 依 据 ， 保 持 连 续 发 展2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 16文 档 管 理 的 内 容建 立 文 档 规 范 ， 培 养 良 好 习 惯制 定 编 写 计 划 ， 明 确 编 写 责 任检 查 文 档 质 量 ， 提 高 利 用 效 率控 制 文 档 范 围 ， 保 护 知 识 产 权实 施 版 本 控 制 ， 有 效 记 录 历 史2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 17文 档 管 理 方 法 ： 如 何 命 名 ？命 名 规 范 的 重 要 性统 一 的 对 外 形 象 （ 举 例 ）有 效 的 文 档 分 类 （ 举 例 ）快 速 的 文 档 查 找 （ 举 例 ）命 名 规 则 的 制 定并 无 统 一 规 则 ， 依 据 项 目 环 境 自 定 义技 巧 1： 确 定 统 一 的 空 白 封 面 和 项 目 名 称技 巧 2： 同 类 型 多 个 文 档 的 命 名 方 法技 巧 3： 文 档 存 储 和 管 理 的 方 法2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 18文 档 管 理 方 法 ： 如 何 保 证 内 容 完 整 ？内 容 残 缺 的 体 现缺 少 项 目 背 景 和 内 容 目 录 （ 举 例 ）缺 少 表 格 和 示 意 图 （ 举 例 ）缺 少 对 思 想 的 阐 述 和 问 题 的 分 析 （ 举 例 ）保 证 内 容 完 整 的 方 法技 巧 1： 提 供 统 一 的 项 目 背 景 资 料技 巧 2： 培 养 一 致 的 文 档 编 写 习 惯技 巧 3： 明 确 要 求 表 格 和 图 形 的 使 用 方 式2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 19文 档 管 理 方 法 ： 如 何 写 好 需 求 分 析做 好 需 求 分 析 的 前 提 条 件客 户 应 用 环 境 的 了 解市 场 主 流 与 技 术 主 流 的 了 解客 户 现 有 需 求 的 总 结 和 潜 在 需 求 的 挖 掘完 成 需 求 分 析 的 过 程第 一 步 ： 项 目 建 议 书 （ Proposal） 第 二 步 ： 市 场 与 技 术 调 研 报 告 （ M&T Report)第 三 步 ： 需 求 变 更 风 险 分 析第 四 步 ： 需 求 分 析 初 稿2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 20文 档 管 理 方 法 ： 如 何 写 好 概 要 设 计做 好 概 要 设 计 的 前 提 条 件客 户 需 求 细 节 的 了 解技 术 重 点 和 难 点 的 分 析系 统 结 构 的 设 计 与 划 分完 成 概 要 设 计 的 过 程第 一 步 ： 功 能 描 述 （ Function Description）第 二 步 ： 功 能 定 义 （ Function Specification）第 三 步 ： 重 点 难 点 问 题 解 决 思 路第 四 步 ： 概 要 设 计 草 案2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 21文 档 管 理 方 法 ： 如 何 写 好 详 细 设 计详 细 设 计 的 底 线 是 什 么 ？主 要 处 理 流 程 的 详 细 说 明对 外 接 口 的 详 细 说 明主 要 逻 辑 结 构 和 数 据 结 构 的 详 细 说 明完 成 详 细 设 计 的 过 程第 一 步 ： 流 程 定 义 （ Control Flow）第 二 步 ： 数 据 结 构 定 义 （ Data Flow)第 三 步 ： 接 口 定 义 （ API Specification）第 四 步 ： 详 细 设 计 草 案2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 22文 档 管 理 方 法 ： 如 何 写 好 里 程 碑 报 告里 程 碑 报 告 的 内 容预 期 目 标 的 解 释 和 说 明已 完 成 工 作 的 说 明进 度 情 况 、 测 试 结 果 的 分 析 和 说 明下 一 步 工 作 的 重 点 和 难 点完 成 里 程 碑 报 告 的 过 程第 一 步 ： 分 析 前 一 个 里 程 碑 报 告 的 内 容第 二 步 ： 说 明 当 前 里 程 碑 的 主 要 进 展第 三 步 ： 总 结 存 在 的 问 题 、 困 难 和 障 碍第 四 步 ： 列 出 下 一 个 里 程 碑 的 主 要 工 作 计 划2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 23文 档 管 理 方 法 ： 确 定 最 小 文 档 集如 何 确 定 最 小 文 档 集重 要 认 识 ： 最 小 文 档 集 不 是 指 最 简 单 文 档 集最 重 要 、 最 必 须 的 文 档 组 成 最 小 文 档 集如 何 实 现 最 小 文 档 集人 员 分 工 ： 多 人 协 作 完 成 一 份 文 档文 档 格 式 ： 提 供 统 一 易 用 的 模 板内 容 组 织 ： 合 并 细 节 结 构 ， 保 持 总 体 完 整2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 24反 思 ： 为 什 么 中 国 人 不 善 于 写 文 档 ？文 化 背 景 的 原 因官 修 史 与 私 修 史 ： 从 孔 子 谈 起封 建 专 制 与 思 想 禁 锢 ： 焚 书 坑 儒 和 文 字 狱现 代 教 育 的 原 因缺 乏 方 法 教 育 和 人 格 教 育缺 乏 法 律 意 识 和 严 谨 态 度官 本 位 、 钱 本 位 的 价 值 观2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 25内 容 提 要文 档 的 分 类 和 等 级文 档 管 理 的 原 则 和 方 法文 档 示 例 与 讨 论2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 26文 档 编 写 技 巧文 档 排 版 方 法问 题 ： 你 会 用 MS Word吗 ？图 表 制 作 方 法问 题 ： 你 会 用 MS Visio和 MS Excel吗 ？文 档 分 类 结 构问 题 ： 如 何 设 计 良 好 的 文 件 夹 结 构 ？文 档 命 名 方 式问 题 ： 如 何 对 自 己 的 项 目 进 行 文 档 命 名 ？2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 27文 档 示 例 与 讨 论需 求 分 析 文 档 示 例研 发 类 项 目 概 要 设 计 与 详 细 设 计 示 例应 用 类 项 目 概 要 设 计 与 详 细 设 计 示 例数 据 库 与 数 据 仓 库 类 设 计 文 档 示 例测 试 计 划 与 测 试 案 例 类 文 档 示 例工 作 日 志 、 周 工 作 报 告 、 里 程 碑 报 告 文 档 示 例2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 28结 束 语软 件 开 发 的 过 程 就 是 文 档 管 理 的 过 程代 码 容 易 遗 忘 ， 文 档 却 长 久 闪 光建 立 文 档 规 范 是 软 件 团 队 的 成 功 之 路2021年 8月 12日 软 件 项 目 管 理 培 训 之 三 文 档 规 范 29