如何写好一份软件需求文档

最近一年以来，由于做系统设计和系统架构工作的需要，输出了不少的软件需求文档。从感知到规控，从应用到底软，从基础模块到中间件，各方面都有所接触。

现在回头望去，看自己第一次写的那一份软件需求，简直是惨不忍睹，不堪入目，也不知道当时的算法同学看到如此的软件需求内心是作何感想。今日下班略早，把这段时间撰写软件需求文档的经验做个总结。

0.前言

首先要说明的是，本文中提到的软件需求，并不是互联网行业中的软件需求，比如开发抢票软件产品的需求；而是自动驾驶系统对ADCU域内各子模块的软件需求。

从头说起，在汽车电子电器架构下控制器功能软件的需求文档，已经存在了清晰的定义，各厂家大同小异。比如在GEEA2.0架构下，功能系统开发链被定义为：项目目标->功能列表->功能描述->功能实现->系统实现->软件规范->产品交付物。

其中每个过程，输出物分别对应：功能特性清单->功能需求描述->功能实现规范->系统需求规范->软件需求规范->产品规格书。

但自动驾驶控制器与传统零部件开发难度不同，即使是这些文档也无法帮助我们完成开发要求。软件需求往往需要拆解到针对自动驾驶系统中某一功能模块的需求，比如系统对感知模块的需求，系统对定位模块的需求，系统对于时间同步的要求等等；这即是自动驾驶系统对ADCU域内各子模块的软件需求。

1.动笔前

一份好的文档，需要在动笔前就梳理好架构以及主要思想，所以在动笔前需要做的工作很重要，简单列举如下几点能想到的：

1. 了解模块的功能和目标：在编写每个模块的需求文档之前，深入了解该模块的功能和目标。对于该模块需要实现的功能以及性能指标，做到心中有数。
2. 了解模块的技术路径和主流算法：通过阅读相关文献、行业标准和技术趋势，掌握该模块的技术路径和主流的算法优势，以便更好地理解模块的需求。这部分有较快的了解方法，就是阅读综述文献。在读研的时候应该很多同学都水过综述，实际上综述确实是外行能够快速了解一个方向的方法。
3. 参考标准和规范：在编写需求文档时，参考相关的行业标准和规范。例如，自动驾驶系统的国家标准、传感器数据标准、控制系统标准等等。这部分行业标准和规范可信度较高，一般也是需要实现的必然要求。
4. 参考竞品性能：在软件模块解耦趋势越发明显的今天，各个模块的性能指标其实都能够在网络中找到。这里推荐笔者使用的两种方法，一种是通过一些比赛或数据集的排名获取当前先进算法的性能指标，比如在nuscence数据集的官网上就有排名；另一种是通过厂家的宣传手册或官网获取，比如定位算法性能指标就可以通过对比某公司高精度定位盒子的性能来定义。
5. 与团队沟通和确认：在编写文档之前，与相关团队成员进行讨论和确认，以确保需求的准确性和可行性。
6. 梳理好文档的架构和脉络：将大纲提前罗列清楚，能够缩短时间明确目标。

2.动笔中

1. 模块简述：需要在文档中对模块有整体的描述，关于该模块在系统中处于什么地位，起到什么样的作用，与哪些模块进行交互等等，让开发人员对该模块有整体性的了解。
2. 明确输入和输出：明确每个模块的输入和输出，信号列表、交互机制。了解输入数据的格式、来源和质量，以及输出数据的格式、目的地和需求。比如该模块接收的数据可能来源于CAN/LIN/以及自身的其他模块，这些数据的格式、单位、频率都不同，这些都是需要明确定义的。
3. 详细描述功能需求：为每个模块的功能需求编写详细的描述。包括但不限于：感知模块的目标、感知数据的准确性和可靠性、感知数据的处理和融合方法、规划模块的路径规划的要求、控制模块的控制策略和控制精度等。这里的很多需求，都应该承接于客户要求，比如自动泊车时揉库次数不能高于6次，等等。
4. 考虑非功能需求：除了功能需求之外，还需要考虑非功能需求。包括但不限于：性能要求（例如响应时间和处理速度）、鲁棒性（对异常情况和错误情况的容忍度）、可维护性（代码的易读性、可扩展性和可测试性）、以及每条需求功能安全等级要求，等等。
5. 使用图示和表格：使用图示和表格可以更好地描述和组织需求。例如，可以使用流程图来描述算法流程，使用数据表来描述数据需求，使用时序图来表示数据交互需求。其实写一份文档和写论文一样，讲究图文并茂，如何能够清晰明确的让算法同学明白开发需求，是这份文档存在的意义。

3.完工后

1. 变更记录：开发是不断进步的过程，也许在后期会发现设计中存在的很多问题，这是正常的事情。每次版本迭代做好变更记录，方便追溯与开发。
2. 召开评审：每次需求更新后，及时召集团队成员进行评审，有经验的工程师会帮助我们快速提升文档质量，也会让开发少走很多弯路。
3. 明确任务：保持沟通，与开发团队和测试团队保持沟通，确保他们对需求有清晰的理解，并能够准确地实现这些需求。
4. 定期维护：在开发过程中，可以定期review一下自己的文档，反思是否有需要更新的地方。

4.总结

总之，编写一份好的需求文档需要细心、耐心和专业知识的支持。一份好的文档，就像自己的孩子，需要用心去照顾，每一次bug的发现以及需求的更新，都是在完善这个软件模块。

有一次为了和算法同学讲清楚需求，画一张图就画了半天的时间。当量产的时候，再回头看这份经历了无数次修改的文档，回想起文档中每一个需求的字斟句酌，总有种蓦然回首的感觉。