软件工程中常见的三类文档分类及其典型代表，分别对应软件生命周期的不同阶段和不同角色的使用需求

软件工程中常见的三类文档分类及其典型代表，分别对应软件生命周期的不同阶段和不同角色的使用需求：

• 开发文档：面向开发人员和技术设计人员，用于指导系统的设计与实现。

  • 可行性研究报告：评估项目在技术、经济、操作等方面的可行性；
  • 软件需求规格说明书（SRS）：明确用户需求与系统功能/非功能需求，是开发与测试的基准；
  • 概要设计说明书（也称总体设计）：定义系统架构、模块划分、接口关系及关键技术方案；
  • 详细设计说明书：描述每个模块内部逻辑、算法、数据结构、类图/流程图等，支撑编码；
  • 数据库设计说明书：包括概念模型（E-R图）、逻辑模型（表结构、字段、约束）、物理设计（索引、分区等）。

• 管理文档：面向项目经理、QA、配置管理员等，用于过程控制与项目治理。

  • 项目开发计划：含目标、范围、进度、资源、风险、组织等整体规划；
  • 测试计划：定义测试范围、策略、环境、用例设计方法、准入/准出标准；
  • 开发进度月报：阶段性汇报进度、问题、变更、人力投入等；
  • 项目总结报告：复盘项目成果、经验教训、质量分析与改进建议。

• 用户文档：面向最终用户、运维人员或系统维护者，强调可读性、实用性与可操作性。

  • 用户手册：面向普通用户，说明系统功能、业务流程、界面操作；
  • 操作手册：偏技术操作，如部署步骤、启动/停止服务、常见命令；
  • 维护手册：供系统管理员或售后支持使用，含故障诊断、日志解读、备份恢复、升级指南等。

这些文档共同构成软件项目的技术资产与知识沉淀，符合CMMI、ISO/IEC/IEEE 12207等标准要求，也是等保测评、软件验收、审计溯源的重要依据。

在敏捷开发模式下，传统“大而全、重文档、先写后做”的文档实践需转向“恰到好处（Just Enough）、及时交付（Just-in-Time）、以价值为导向”的原则。调整核心在于：减少冗余、提升实效、支持协作、随演进更新。具体调整策略如下：

✅编写粒度调整

• 从“全面覆盖”转向“聚焦价值”：
  • 不再追求《概要设计说明书》《详细设计说明书》等全套重型文档，而是用轻量级制品替代，如：
    • 架构决策记录（ADR）——记录关键架构选择及理由（如“选用微服务而非单体”）；
    • 白板草图/PlantUML序列图/组件图——用于站会或结对编程时即时沟通；
    • 内嵌代码注释 + Swagger/OpenAPI（API文档）、Javadoc/TypeScript接口定义（契约文档）。
• SRS → 用户故事地图 + 接受标准（AC）+ 原型/线框图：
  每个用户故事（User Story）附带清晰的业务价值、验收条件（Given-When-Then）、必要UI示意，取代长篇SRS文本。

✅交付节奏调整

• 与迭代（Sprint）同步，小步交付、持续演进：
  • 文档不是项目初期“一次性产出”，而是按需生成、按需更新：
    ▪ Sprint计划会中明确“本迭代需产出/更新哪些文档片段”（如：新增支付模块的API文档、更新部署手册中的配置项）；
    ▪ 每次集成/发布后，自动触发文档构建（如Docs-as-Code，用MkDocs/Sphinx+Git管理）；
    ▪ 测试计划拆解为“Sprint测试策略卡”，含本迭代测试重点、环境准备、自动化覆盖率目标。
• “文档即代码”（Docs as Code）实践：
  • 文档与源码同仓（如GitHub/GitLab）、同分支策略、同CI流水线；
  • 支持Markdown编写、PR评审、版本比对、自动发布至内部Wiki或静态站点。

✅角色与责任重构

• 文档不再是“文档工程师”专属任务，而是全员共建：
  • 开发者写API文档和关键算法注释；
  • 测试人员维护验收用例库与缺陷知识库；
  • PO协同编写用户故事与业务规则说明；
  • DevOps工程师维护部署手册与监控告警指南。

⚠️ 注意：“轻文档”不等于“无文档”——关键决策、合规要求（如医疗/金融行业）、系统交接、安全审计仍需保留必要、可追溯、可验证的文档证据。

示例：敏捷版“数据库设计”交付方式 - 初始：ER图（Draw.io/Mermaid）+ 核心表DDL脚本（含注释）存于`/docs/db/`目录； - 每次Schema变更：提交DDL变更脚本 + ADR说明“为何增加soft_delete字段”； - 自动化：CI中运行SQL lint + 生成在线数据字典（如Skeema或DBT docs）。