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

baoshijie

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

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

0.前言

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

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

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

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

1.动笔前

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

了解模块的功能和目标：在编写每个模块的需求文档之前，深入了解该模块的功能和目标。对于该模块需要实现的功能以及性能指标，做到心中有数。

了解模块的技术路径和主流算法：通过阅读相关文献、行业标准和技术趋势，掌握该模块的技术路径和主流的算法优势，以便更好地理解模块的需求。这部分有较快的了解方法，就是阅读综述文献。在读研的时候应该很多同学都水过综述，实际上综述确实是外行能够快速了解一个方向的方法。


参考标准和规范：在编写需求文档时，参考相关的行业标准和规范。例如，自动驾驶系统的国家标准、传感器数据标准、控制系统标准等等。这部分行业标准和规范可信度较高，一般也是需要实现的必然要求。

参考竞品性能：在软件模块解耦趋势越发明显的今天，各个模块的性能指标其实都能够在网络中找到。这里推荐笔者使用的两种方法，一种是通过一些比赛或数据集的排名获取当前先进算法的性能指标，比如在nuscence数据集的官网上就有排名；另一种是通过厂家的宣传手册或官网获取，比如定位算法性能指标就可以通过对比某公司高精度定位盒子的性能来定义。

与团队沟通和确认：在编写文档之前，与相关团队成员进行讨论和确认，以确保需求的准确性和可行性。

梳理好文档的架构和脉络：将大纲提前罗列清楚，能够缩短时间明确目标。

2.动笔中

模块简述：需要在文档中对模块有整体的描述，关于该模块在系统中处于什么地位，起到什么样的作用，与哪些模块进行交互等等，让开发人员对该模块有整体性的了解。


明确输入和输出：明确每个模块的输入和输出，信号列表、交互机制。了解输入数据的格式、来源和质量，以及输出数据的格式、目的地和需求。比如该模块接收的数据可能来源于CAN/LIN/以及自身的其他模块，这些数据的格式、单位、频率都不同，这些都是需要明确定义的。

详细描述功能需求：为每个模块的功能需求编写详细的描述。包括但不限于：感知模块的目标、感知数据的准确性和可靠性、感知数据的处理和融合方法、规划模块的路径规划的要求、控制模块的控制策略和控制精度等。这里的很多需求，都应该承接于客户要求，比如自动泊车时揉库次数不能高于6次，等等。

考虑非功能需求：除了功能需求之外，还需要考虑非功能需求。包括但不限于：性能要求（例如响应时间和处理速度）、鲁棒性（对异常情况和错误情况的容忍度）、可维护性（代码的易读性、可扩展性和可测试性）、以及每条需求功能安全等级要求，等等。

使用图示和表格：使用图示和表格可以更好地描述和组织需求。例如，可以使用流程图来描述算法流程，使用数据表来描述数据需求，使用时序图来表示数据交互需求。其实写一份文档和写论文一样，讲究图文并茂，如何能够清晰明确的让算法同学明白开发需求，是这份文档存在的意义。

3.完工后

变更记录：开发是不断进步的过程，也许在后期会发现设计中存在的很多问题，这是正常的事情。每次版本迭代做好变更记录，方便追溯与开发。

召开评审：每次需求更新后，及时召集团队成员进行评审，有经验的工程师会帮助我们快速提升文档质量，也会让开发少走很多弯路。


明确任务：保持沟通，与开发团队和测试团队保持沟通，确保他们对需求有清晰的理解，并能够准确地实现这些需求。

定期维护：在开发过程中，可以定期review一下自己的文档，反思是否有需要更新的地方。

4.总结

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

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

mizhongquan

关于如何写好一份软件需求文档，以下是我的专业回复：

针对汽车电子电器架构下的控制器功能软件需求文档，首先要明确目标并深入理解自动驾驶系统的整体架构。在撰写时，需确保清晰、准确、具体地描述各子模块的软件需求，避免模糊和歧义。可按照以下步骤进行：

一、前言：简述文档目的和适用范围，明确本文所指的软件需求是自动驾驶系统ADCU域内的各子模块软件需求。

二、概述：描述自动驾驶系统的整体功能，以及各子模块在系统中的角色。

三、详细需求描述：逐一对各子模块的软件需求进行描述，包括输入/输出、性能要求、安全需求等。

四、需求规格：明确软件需求的规格和标准，如通信协议、数据处理算法等。

五、测试与验证：描述如何对软件需求进行测试和验证，以确保其满足规格和要求。

六、附录：附上相关图表、流程图等辅助资料。

在撰写过程中，还需注意文档的结构清晰、层次分明，并且不断总结经验，持续改进和完善文档撰写方法。通过这样的方法，可以大大提高软件需求文档的质量和效率。

mizhongquan

好的，关于如何撰写一份优秀的软件需求文档，作为一名汽车工程师，我有以下专业建议：

一、前言：明确说明文档适用的领域，如本文适用于自动驾驶系统ADCU域内各子模块的软件需求。

二、目标与背景：简述文档撰写的目的和背景，包括系统设计和系统架构的需求。

三、需求概述：详细列举软件需求的概要，包括感知、规控、应用、底层软件、基础模块和中间件等各方面的需求。

四、具体需求描述：
1. 清晰定义每个需求的业务场景和使用场景。
2. 描述需求的具体功能和技术指标，如性能、准确性等。
3. 对需求的优先级进行划分。

五、需求间的关联：描述各需求间的逻辑关系，如某一需求的实现会如何影响其他需求。

六、非功能需求：包括安全性、可靠性、可维护性、可扩展性等要求。

七、验收标准：明确软件需求的验收方法和标准。

八、附录：如有必要，可附加相关图纸、流程图等辅助资料。

九、总结与建议：结合个人经验，强调撰写软件需求文档的重要性，并提出改进建议。

撰写软件需求文档需严谨细致，确保准确性、完整性和清晰性，以便相关团队准确理解和实现需求。希望以上建议对您有所帮助。