开发文档分析

传统的瀑布模型的开发过程中的文档过重，需要大量时间编写各种文档，比如软件需求规格说明书， 概要设计，详细设计等等。现在的普遍采用的敏捷开发模式，而敏捷宣言中有工作软件胜过全面的文档，意图是最好把更多的注意力放在软件上，而不是把时间花在过于详细的前期文档上。因此，文档应该尽可能轻量化，只写必要的。

软件开发中的文档大致分为两类，一类是临时文档，在开发过程过程中产生和使用，每轮迭代周期结束后就归档，不再使用，以后最多用于追溯。另一类是持久性文档，一直需要维护更新，常常伴随着软件产品的整个生命周期。持久性文档主要有产品需求说明、设计文档、接口文档、 运维手册、使用说明等。临时性的文档有敏捷周期的故事、任务分工、开发计划和进度、设计、缺陷记录、测试报告、发行说明等。

持久性文档

• 产品需求说明

目的主要了解产品的功能和价值，形成总体上的了解。面向主要公司内部相关人员，产品经理、研发、测试、设计团队、运维等人员。主要内容有：

设计文档目的让相关开发人员能够快速熟悉系统设计结构， 从而能让新来人员快速进入相关的模块开发和维护工作。当设计架构发生变化，应及时更新。

接口文档一般给开发人员使用，用于评审和对接。实现一般推荐使用yapi 接口管理软件 ，它能和swagger 的api接口进行同步，这样维护简单，可读性也好。

• 运维手册

顾名思义主要给运维角色的人员使用，随着开发的功能不断发布，运维手册也需要及时更新。手册内容主要包含以下内容：

说用说明主要是面向用户的，一般简单易懂，展现方式不一定文字图片，可以提供视频。使用说明一般不是研发来写，可以是测试 或 运维 或产品经理等。随着新功能发布，使用说明也会同步更新。

临时性文档

• 用户故事

敏捷开发需求主要通过用户故事描述，维护用户故事就是维护需求。用户故事在开发时使用，开发后已经转成产品，直接通过产品和使用说明了解功能。一般通过敏捷项目管理软件来维护，例如，tapd等。用户故事有史诗级，得分解成子用户故事。在规划迭代周期时，安排需要开发那些用户故事。在开发时，相关人员讨论细化用户故事的需求，然后进行任务分工。开发完后，归档这些迭代故事。

• 概要设计

如果需求简单，在做用户故事的需求分析时，顺便就把设计实现方案讨论出来了。如果有一定复杂度，最好写一下简单设计文档，方便项目组内沟通、评审。

概要设计一般要写本次需求牵扯那些模块修改开发，以及每个模块分配的任务职责，并描述涉及模块的大致交互关系，有复杂算法和关键决策的最好详细描述一下。再设计一下各个模块的API接口的简单说明 和 数据表的说明， 然后再把该概要设计文档发给相关人员，阅读评审。评审通过后，再设计详细的API接口和数据表，然后评审，这些设计可以直接写代码和在数据库上建立数据库表直接实现。如果本次需求设计影响较大，那么在开发完后，需同步修改持久性的设计文档。

• 软件测试报告

软件测试报告是描述测试流程、方法、结果及结论的文档，主要目的是向项目相关方提供有关软件质量的客观信息。以下是软件测试报告的主要内容：

本轮迭代周期开发测试完成后，上线发行前，要输出一个发行说明，它向用户、开发者和维护者提供有关软件新版本或更新包的详细信息。发行说明通常包括但不限于以下内容：

发行说明是用户了解软件更新内容、决定是否升级以及如何准备升级的关键资料，同时也是开发团队与用户沟通变更、展示进步和透明度的重要方式。

总结

临时性文档主要用于开发过程中，开发完后归档，不再发生变动。持久性文档一直在维护中，随着开发的进行，需要及时变更相关内容。文档不再详细，只要起到合适的沟通目标即可。最详细的文档应该是源代码，所以源代码的注释和可读性在开发时需要特别关注。