软件工程之需求文档

一、背景

　　在项目管理与软件开发过程中，一直要求相关文档的编写、交付、存档，但是具体到项目中，因为项目的开发人员文档软实力不高、项目周期比较紧、开发规范未要求等因素导致很多文档都是缺失的状态。结合自己多年开发经验，在需求文档、解决方案、设计文档、测试文档等基本没有很好执行，都是靠开发人员口口相传或者通过数据表注释、代码注释、原型来理解业务需求。通过学习软件架构师能力要求，多年工作的体会，当前正在编写系统设计文档的过程，特意写一篇工程师的软实力——文档编写，工程师的软实力包括英语交流与阅读能力、团队沟通与协作能力、文档编写与讲解能力。所以作为一个合格的工程师或者系统架构师，软件文档编写能力是必须提升。

　　当然，软件工程是不断发展的课题，很多旧的方法论或者要求，会不适用当前的技术发展。所以我们在实际开发中对软件文档的编写会存在不一样的要求，比如在瀑布式开发、敏捷软件开发、Devops开发模式中需要的文档各异。通过对文档的编写、使用、存档的过程，对于文档的内容格式要求——1、文档格式要求，各类型文档整体结构（标题）、字体大小必须统一标准（方便阅读、层次清晰、减少差异）；2、文档内容要求，各类型文档严格按照使用群体编写，需求文档（业务、开发）不涉及具体技术实现、解决方案（业务、管理人员）、设计文档（技术人员、详细技术实现）不同人员侧重点不一样，对于需求文档要求清晰的业务规则说明、并且一一枚举。对于设计文档要求系统架构、技术架构、表数据存储等；3、文档迭代要求，各类型文档版本、迭代更新的要求，保证相关人员一致的认识。通过下述内容，按照不同类型，总结不同文档特性、文档格式、文档内容、文档迭代的要求。

二、文档结构

　　通过上述的思维导图，包括其它产品书、语雀和云效的需求文档（需求规则说明、PRD）基本一致。按照各个主要节点编写相关内容，反映业务需求，提供开发理解，系统历史存档的要求。

三、文档介绍

　　1、版本记录，是需求文档非常重要的一部分，因为很多需求都是会产生变更的，特别是在一些比较大的需求，这就导致了版本记录的必要性。如果没有版本记录，会导致业务方无法完全了解整个需求的变动情况、开发方开发过程需求不断变更，没有变更记录难以理解。版本记录包含日期、版本号、修订人和修订描述，其中需格外注意的是修订描述，通过对修订描述言简意赅的描述实现大家一致的理解，历史追溯。

　　2、需求说明，包括需求来源、需求背景和需求目标，需求来源主要记录需求的所属项目、需求提出人和主要的负责人（需求负责人、研发负责人、测试负责人、相关业务方、领域专家）。需求背景主要描述需求产生的背景，即为什么要做这个需求。需求背景的书写切不可流于形式，深入的理解需求背景可以更好的理解当前公司的战略方向，因为每一个需求都是公司战略执行层的具体表现。需求目标则是描述需求实现的目标，即要做什么。需求目标可大可小，小至功能目标，大至业务目标，需把握好需求目标的尺度。

　　3、名词解释，名词解释主要解释该需求的专业名词，让用户更好的理解需求。例如在票据行业中的背书、贴现、前手等专有名词，是有必要在对应的需求中进行阐述说明的。名称解释目的让业务需求方、系统开发方对相关业务术语保持一致认知、减少因为理解偏差带来的系统偏差。

　　4、需求列表，需求列表记录了具体需求，即怎么做。对于历史项目/需求的更新，需求列表则尤为重要，在需求列表中描述本次需求的变更点，可以让研发/测试更好理解本次的需求内容，起到了总的概览作用。

　　5、详细需求说明，详细需求说明需包含UML图、原型图和详细逻辑说明。UML图在正常的需求中起码要包含活动图/时序图+状态机图（UML这么画请看这篇文章），一个逻辑清晰的图可以胜过千言万语；原型图和详细逻辑说明相辅相成，构成了需求文档篇幅最大的部分，是对「怎么做」的更加详细的描述，详细到页面如何跳转、按钮的交互逻辑、字段的展示逻辑等，对于复杂的业务规则分条陈述、描述清楚。

　　6、问题，问题主要记录需求评审过程中参会人员提出了相关问题，其中若未能当场给出解答的部分，则需对问题和结论进行记录。

　　7、暂不支持记录当前需求无法实现的部分。正常情况下，需求评审之前应对需求的可实现方案进行初步沟通，即和研发通通气，这样可以避免评审过程针对不可实现的打断问题。

　　8、性能需求包含并发量、响应速度等一系列系统性能相关的需求。性能需求相关的内容偏向于技术层面，涉及技术问题，与开发沟通确认。

　　9、数据需求包含数据量、存储时间等，这与单独的报表需求不同，涉及技术问题，与开发沟通确认。