如何编写优质的需求文档

  • 时间:
  • 浏览:30
  • 来源:小虫网

  编写需求文档,在嵌入式开发领域是非常普遍的。需求文档被用来定义开发任务,协调大规模的研发计划。对于最终的产品,需求文档扮演着开发者行为和消费者行为之间沟通纽带的角色。当需求文档书写正确的时候,便可以发挥巨大的作用。然而,如果你在嵌入式开发领域工作的时间足够长,你就会很快发现,这个领域里不合格的需求文档实在是太多了。当你尝试对这些不合格的文档进行修复时,你又会很快发现,书写正确的需求文档绝非易事。在这里,我们提出一些建议,希望能将书写正确需求文档这件事情变得清晰一些。

  从较高的层次来看,书写需求文档的目的就是要提供对所需行为的有效描述。该所需行为可用一个黑盒系统描述,并需要注意以下细节:

   工程师可以根据系统所说进行实现

   测试人员,在不与开发人员沟通的前提下,可以利用满足硬件要求的设备验证需求。

   最终产生的成果满足终端用户的要求。


  黑盒测试书写优质的需求文档:


  最基本的原则是:需求文档应当尽量简洁,用最易懂的描述来约束系统的预期行为。如果你遵循这个原则,剩下的那些重要因素(可测试性、避免过度设计等等)都将变得顺理成章。

  列举一下更详细的规则,通常会更有帮助。下面是书写优质需求文档需要遵循的步骤:

  1. 定义系统的边界。这也是黑盒系统所必要的。

  2. 定义输入和输出。这也应当是你看待内部系统的唯一方式。

  3. 用最易懂的方式描述系统的预期行为

  4. 除了输入和输出之外,你的需求是不是还涉及了系统的其他部分?如果是,那么你的需求就设计过度了。重构需求,让它变得精简。

  5. 你的需求是不是过于模棱两可?加入更多的限定规范。注意:有些模棱两可的描述并不是坏事,假设描述所包含的所有情况均可被接受,且测试的时候不需要附加的信息加以说明,那么就没关系。你不需要(也不应该)把系统的行为限制得过头。

  6. 你的需求是否可测试?(这里指的是黑盒测试)如果不是,你最好返回到第4步。如果这种返工发生很多次,那就说明你的黑盒无法正确描述系统,或者你的测试工具不够优秀。无论是哪种情况,不可测试的需求文档几乎就是一文不值的。

  7. 你的需求文档通俗易懂么?如果你的需求文档非常难以读懂,那就说明你写得不好,只能给那些照着你的需求负责实施的人带来无尽的痛苦。如果是这样,回到第3步。

  8. 你是不是真的做到了第4步?你确认么?再检查一下。

  例子:下面的例子,让我们描述一个自制的嵌入式设备的需求,这个设备能从弯曲传感器上读取弯曲的频率,并根据不同的频率值让一个LED闪烁。

  显然,我们已经完成了步骤2和步骤3了!

   输入:从弯曲传感器读取数据。

   输出:LED。

  但是我们跳过了步骤1:

   在这个例子里,我们将把黑盒画到设备的微处理器上。

  让我们继续往下进行,

  第四步:除了输入和输出以外,我们是否还涉及了其他的系统边界?

   微处理器并不关心从弯曲传感器读取什么样的数据,从处理器的角度来看,仅需要做的是测量ADC脚的电压而已。

   LED仅由数字输出脚控制。

  下面,让我们来修正这个问题:

  第0版本的需求:

  1. 该设备应当根据ADC脚的不同频率的电压,来切换数字输出端的状态。

  第五步: 需求写模棱两可么?

  恩,我们的描述太模棱两可了.输出端切换的速度要多快? 跟电压的关系如何? 输入电压的范围是多少? 让我们加一些更细节的描述吧:

  版本0.1

  1. 输出端应当由一个自由活动的定时器进行控制

  2. 自由运行定时器的频率最高不得高于每秒10次,不得低于每秒1次.

  3. 自由运行定时器的触发频率应当在最高和最低值之间呈线性变化,并与ADC端的输入电压成正比.

  4. ADC端的输入电压应当每100毫秒读取一次

  5. 当ADC端的输入电压端被读入时,控制自由运行定时器周期时间的注册值也应当被更新.

  6. ADC输入端的电压有效范围应当被控制在0到1伏之间.

  第六步: 你的需求是可测试的么?

   首先,自由运行的定时器在这里不需要提及. 因为对它基本上无法进行黑盒测试,它既不是输入也不是输出,而且跟这两者也没有什么联系。

  让我们用数字输出端变化的频率应控制在每秒10次和每秒1次之间来代替自由运 行定时器的测试标准。

   对于上述的第四条需求,可能需要一些小修改才能作为测试标准。让我们用ADC端的输入电压应当保证在每100毫秒内至少被读取一次来加以描述,这样的描述能让我们预期的测试行为显得更加通俗易懂。

   需求的第五条也需要一些小修改。我们如何才能检测电压的输出范围是在0到1伏之间呢? 总不能给个2伏的电压,然后看看元器件有没有被烧毁吧?

  那么,说检验系统在ADC端输入电压为1到2伏之间的时候,工作是否正常,这样就检验就容易多了。需求描述应当是正面的,应当描述设备应该的行为,而不是设备不应该的行为。否则的话,测试将会无法进行。

  版本0.2

  1. 数字输出端的切换频率应当控制在每秒10次到每秒1次之间

  2. 数字输出端的切换频率应当在最大值和最小值之间呈线性变化,并与ADC端的输入电压成正比

  3. ADC端的输入电压应当保证在每100毫秒内至少被读取一次

  4. 检验当ADC端的输入电压范围在0到1伏之间的时候,系统工作是否正常

  第七步:你的需求是否通俗易懂?

  相比于我们原来的描述:根据弯曲传感器的输出不同频率来控制LED闪烁,我们上面的那些需求描述显得难以阅读和理解。

  我发现,让需求文档变得通俗易懂,最简单办法莫过于,把过于细节的东西抽取出来,然后以条目的形式单独定义。

  版本1

  1. 弯曲传感器应当保证至少在100毫秒内读取一次数据(放到注释单独列出)

  2. 切换LED的状态,使其与弯曲传感器的读数保持一致

  3. 当弯曲传感器的读数为1伏特时,LED状态切换的次数应当保持在平均一秒十次;当传感器的读数为0伏特时,LED的切换次数应保持在一秒1次。

  定义:

   弯曲传感器:输入电压位于ADC的X端。安全电压范围为0到1伏特(放到注释单独列出)

   LED状态:数字状态由Y端输出

  这样就好多了(尽管还不完美)。这些需求通俗易懂,不涉及到系统内部实现,且易于测试。对于系统行为的限定也仅仅限于需要做什么,点到为止。(例如,对弯曲传感器的采样频率,在实现上也可以更高,只要不产生非预期行为,一切都可以)。

  编写需求就仿佛是在大脑中构建软件的过程。因此要重于执行操作。

  英文原文:How to write good requirements

猜你喜欢

全国近10万部手机被感染控制

“这是你孩子的成绩单”“这个人你看认识吗?”……收到这类熟人短信,点开短信中附带的链接,手机就会被植入木马,银行卡里的钱能被洗劫一空。近日,安徽省淮北市警方成功破获一起“短信大盗”木马盗刷案。在360安全中心的技术支持协助下,淮北警方摧毁了木马制作、传播、盗刷、销赃整个犯罪团伙,跨越四省抓获9名犯罪嫌疑人。据初步调查,短短半年时间,全国近10万部手机被木马感染,近800人遭遇经济损失,团伙诈骗金

2019-07-15

前搜狐视频高管马可违反竞业限制案宣判 搜狐获胜

8月28日消息,前搜狐视频版权影视中心总经理马筱楠(马可)违反竞业限制义务被搜狐提起仲裁一案,已经宣布裁决结果,搜狐获胜。裁决结果显示,马可违反了竞业限制义务履行的约定,应承担违约责任,向搜狐双倍返还违约期间已收到的竞业限制补偿金,并继续履行对搜狐的竞业限制义务。今年2月底,马可从搜狐视频离职。她与搜狐签署的《劳动合同》中,明确包含了《不竞争协议》,约定了其离职后的竞业限制义

2019-07-15

四季沐歌畅享净水机纯净双出水,一机两用,适合家用

随着经济收入的增加,居民对生活品质越来越讲究,很多家庭开始关注日常饮用水是否纯净,同时对净水机的需求也逐渐增多。目前,我国市场中净水机企业高达4500多家,但真正掌握核心制造技术、赢得消费者肯定与信赖的企业并不多。携手清华大学、对净水机核心

2019-07-15

如何编写优质的需求文档

编写需求文档,在嵌入式开发领域是非常普遍的。需求文档被用来定义开发任务,协调大规模的研发计划。对于最终的产品,需求文档扮演着开发者行为和消费者行为之间沟通纽带的角色。当需求文档书写正确的时候,便可以发挥巨大的作用。然而,如果你在嵌入式开发领域工作的时间足够长,你就会很快发现,这个领域里不合格

2019-07-15

qq红包一元免费领取朋友圈被"8"刷屏 你肺活量有没有被嘲笑?

不知从什么时候开始,就有不少朋友在朋友圈里发8,后面有一句话解释:这是一款测肺活量的游戏,憋气(记者注:也有传是呼气),拿起手机打8,正常人是5行,超人是9行,少于5行的证明肺活量不行要戒烟了,少于3行要去医院了。到昨天下午,许多人的qq红包一元免费领取朋友圈里已变成了8的海洋。打8测肺活量游戏,昨天也一度位列新浪微博热门话题榜的第4位。昨天,你的qq红包一元免费领取朋友圈被8刷屏了吗?搜了一下,这个游戏前天晚上开始在网上出现

2019-07-15