如何编写优质的需求文档

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

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

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

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

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

 

黑盒测试

 

书写优质的需求文档:

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

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

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端输出

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

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

 

英文原文:Job Vranish   编译:伯乐在线 – 黄小非

源地址:http://blog.jobbole.com/15561/

Stephen Wolfram:以数据诠释人生

Stephen Wolfram 是一个天才,关于数据的一切,很少有人比他更精通,毕竟他是 Mathematica 以及 Wolfram|Alpha 的发明者。最近,他利用了数据制作了一份个人生平总结,让我们一起来看看。

第一张图片展示他自 1989 年到 2012 年间发电子邮件的记录。其中 1989 年至 2002 年间,他发邮件的时间都非常不规律,之后便趋于稳定。Stephen 说他会在一天中的任何时候发电子邮件,甚至在午餐小憩的时候也会发。生活基本上两点一线:邮件、睡觉。一般他会在凌晨 3 点入睡,然后在上午 11 点时起床。

不过,为什么从 1989 年到 2002 年,他发电子邮件的时间如此不规律——作息时间如此不规律?他解释,那段时间里,他正投入大量的精力到《A New Kind of Science》这本书中。而当 2002 年,这本书终于完成之后,他就开始规律作息的生活。

第二张图片也与电子邮件有关。这张图片统计了 Stephen 每日、每月发送邮件的频率,同样,是从 1989 到 2012 年,我们会发现这频率在增高,其中一个高峰在 2009 年。原因是,Stephen 公司的项目越来越多,而在 2009 年正好是 Wolfram|Alpha 上线的时候,所需要的准备也相当的多,大量的沟通成为必要。

第三张图片依然和电子邮件有关,看来收发电子邮件是 Stephen 主要的日常沟通手段。这张图片显示他月均接收到的电子邮件的数量,随着公司的发展,他收到的邮件也越来越多,不过从另外一个方面也证明他直接联系的人很多,公司实际上没有很好的管理。而近期电邮收发数量有所下降则反映了公司得到了更好的管理。

总之,如果把 Stephen 每天接受的和发送的邮件算在一起,那么就是下面这个图:

而从 2002 年开始,Stephen 每天每天敲击键盘的次数,从上方的分布图而言,和 Email 的分布图在图形上是基本一致的。有趣的是,他还记录自己敲击每个按键的次数,意外的发现,退格键(backspace)的敲击次数占据了 7% 的比例,这是他以前没有想到的。

除了电子邮件以外,他还统计了自 2000 年以来,记录在日历上的事件。我们可以看到,自 2002 年后,日历上的事件开始增加,而且 2002 年之前的事件是很少的,这和他花大量的精力和时间投入到《A New Kind of Science》有关。然而,书完成了之后,他就开始投入更多的精力到公司事务上,随着事务的增加,一些例行的事务也开始增加。

Stephen 提到他管理公司的方式是通过电邮和电话“遥控”,因此电话的数字也是一个很重要的数据统计。从分布图来看,频率和发电邮的频率相差不大。

如果就 Stephen 的一天而言,各个时间段会去做什么事情,则可能是以下的趋势:

另外,他还记录了完成《A New Kind of Science》所花费的时间。我们可以看到,这本书集中写作的时间在 2001 年。但,书的第十二章则从 1999 年开始不停的编写和修改,所花费的时间和精力是最多的。

尝试以数据诠释自己的人生的,不止 Stephen 一个,我们曾经报道过 Nicholas Felton,他是信息图天才,从 2005 年开始就用信息图的方式制作个人年终总结。然而,两者的风格并不一致,Nicholas 更加有设计感,更加注重图形化表达,而 Stephen 则更加注重数据本身,更加喜欢从更多维度出发去捕捉、统计数据,说不上孰优孰劣。

只是,如果要我制作这么一份数据,应当如何做呢?

豆瓣为何要做阅读,怎么做?


照片 (1)_副本_副本

今年 1 月,豆瓣发布了豆瓣阅读器产品,并提供了部分内容给读者试读。爱范儿之前曾经关注、报道过豆瓣推出的豆瓣阅读器。在美国,亚马逊早已开始拓展数字出版领域,并且从传统出版行业挖来领军人物,开始绕过出版社直接挖掘作者,自行编辑并出版数字内容。在国内,数字出版正成为热潮,京东、当当等大型电子商务公司正在进入这个领域。而作为文艺用户比较集中,天然地与书比较亲近的豆瓣,也在这个时候推出了自己的投稿出版系统和阅读器产品,打造自己的数字出版和阅读平台。

豆瓣阅读并不仅是将出版界已有纸书数字化,而是提供平台供作者直接发表自己的作品。在采用的出版模式中,豆瓣又不是提供自由市场,使得内容像博客或者日记一样点击发布就能被看到,而是采取了提供优质内容的策略。它的角色部分像是出版商,以编辑的角色深入到内容加工的环节中,对内容先做一筛选。

针对豆瓣阅读为何做,到底想怎么做,我们就此询问了豆瓣阅读的负责人 Scallet,她给我们提供了部分答案。从中,我们也看到了豆瓣阅读的一些趣味和情怀。

这只是一个产品和平台的第一步开始,也许将来这个初生的孩子会有更明晰的模样,但眼下,我们听听豆瓣阅读是怎么想的。

 

为什么要做豆瓣阅读?

最初为什么做豆瓣阅读?它是来自于我们和创作者的谈话。我的一位同事是非常好的诗人。她对我们说,作者的写作是一个逐步成熟的过程,他会不断地写各种中篇、短篇、游戏性作品,包括尝试翻译,这些东西大部分会成为“抽屉作品”。结集出版为纸本不知道要到何年何月,投稿给杂志也需要很长时间才能得到反馈。“如果我们能发表这些不断创作中的抽屉作品,内容会丰富多少!”

那这些内容会有人要读么?

“当然!它们一样有非常出色的内容,而且你可以见到一个作者不断成熟的过程。”

与北大五四文学社见面的时候,他们拿出六本《未名湖》,这份诗歌选集每年出一本,集合了当年最好的青年诗人的作品。它基本没有被销售,因为没有渠道。“也尝试去淘宝上卖,但完全卖不出去。”豆瓣上有真正在读诗歌的人。《未名湖》在豆瓣阅读发表,能让这些诗出现在真正喜欢它们的读者面前。

台湾作者陈辉龙会在豆瓣上发布自己 1994 年出版过的《南方旅馆》。它那么久之前出版,但它仍然足够好。而年轻的科幻小说作者陈楸帆把他 2011 年的最新三个中篇投递给了我们。还有第一次尝试写像模像样的作品的人,(对,也许就是你)因为我们 3 月底要发布的 deadline 在督促自己给作品结尾。

如果说我们是因为传说中巨大的电子书市场份额要做豆瓣阅读,还不如说,我们是在和作者、读者的对话中,看到了那些实实在在对豆瓣阅读的需要。生机勃勃的内容每天都在产生,它们在要求新的发布方式。让抽屉作品及时出现、让绝版作品重新出现、帮那些正在写作的人找到感兴趣的精准读者……这些是我们正在做的,很小的事情。

同时,我们为能做这些小事感到荣幸。

 

豆瓣阅读提供作品,而不仅是图书

每一个写作者创作的天然单位是作品,图书只是一种出版单位,将一定长度、一定主题的东西集结成书,它会带来很多局限。所以,我们将直接售卖单篇作品。一组诗歌、一篇中篇小说、《科学美国人》上的长篇主题文章,都是可以独立售卖的作品。将内容摆脱“书”的形式限制,还原到作品这个层面后,创作和阅读都将更为自由。

这意味着,创作者可以第一时间发布作品,而无需等待结集。作品本身的价值高低也不再以长度来定义。以作品为单位,会使平均阅读时间变短么?也许会。如果每篇作品大概在 1 - 2 个钟头之内读完——你一天刚好的空余时间——也许是对读者更好的变化吧?

这绝不意味着内容水准的下降。相反,我们的第一期售卖内容是一些“真正值得读”的东西。它们配得上你的阅读时间。《世界文学》、《环球科学》、《九州幻想》、《世界建筑》、黑蓝、副本都是我们的内容合作方。你还会见到非常优秀的个人作者,他们选择通过豆瓣阅读发布作品。我们希望,真正有价值的作品,已经出版过也好,从未面市也好,都在我们的平台上和读者见面。

 

依靠读者社群,做社会化阅读

我们会用整个豆瓣擅长的东西来做阅读服务,而不仅是售卖电子书。这些擅长的事情包括:根据用户的阅读兴趣做个性化推荐、遵循评论的传统、让每篇作品都有一个活的读者沙龙。在更具体的作品情境下提供兴趣交流,这会产生很多新的可能。

 

关于作品审读

目前我们给第一批作品设立了少许门槛,所有投稿需要经过编辑的审读,确认品质良好才能参与第一期的售卖。但最终我们会取消这个环节,它太缓慢。我们是一个作品平台,个人作者的投稿只要符合出版法规,都可上架。

那我们如何完成甄选呢?依靠豆瓣的读者。

我们会启动“首批读者计划”,部分读者获得机会最先免费读最近一周、或者一月的新上架作品并且给出评价。这些”首批读者“是每月随机挑选,不会重复,并且保证自己会公正评价的人群,他们会身挂小牌表示评论是出于自然阅读的结果。依靠第一批读者的最初意见,我们可以既保证作品的多样性(不因编辑好恶来取舍),又可以让作品快速完成第一次甄选,获得最初的注意力。

 

图书试读如何纳入豆瓣阅读

我们希望出版社将新书试读放入我们的免费作品栏目。在豆瓣阅读器里,试读样章的阅读体验比网页上好太多。我们会将整个豆瓣读书的试读方式都转移到现在的平台里来。如果出版社愿意提供电子版售卖,他们将更直接地看到阅读样章和购买之间的转化率。

css.php