是什么让一个好的规格？

一位在该项目的乔尔测试是一个项目/公司应该有一个规范.

我想知道什么使规格好.有些公司会编写大量无用的规范,没有人读过,其他公司也不会写下任何东西,因为"无论如何都不会读任何东西".那么,你对你的规范有什么看法？两个极端之间的良好平衡是什么？有没有什么特别重要的,真的,真的(!)应该总是记录在规范中？

最好的规格是:

存在

描述什么,而不是如何(没有解决方案)

可以尽可能少地解释

分布广泛

被所有有关各方同意作为规范

很简洁

是一致的

随着需求的变化定期更新

尽可能详细地描述问题

是可以测试的

什么放在一个规范中

您需要查看规范的受众并找出他们需要知道的内容.它只是您和商业赞助商之间的文件吗？在这种情况下,它可能相当轻量级.如果它是一个100多年的J2EE项目的功能规范,它可能需要更多细节.

观众

关键问题是:谁将阅读规范 - 规范将有几个潜在的利益相关者:

注销系统的业务所有者.

正在构建系统的开发人员(可能是也可能不是你)

质量保证人员必须为此编写测试计划.

维护人员希望了解系统

其他项目的开发人员或分析人员可能希望将其他系统集成到其中.

典型主要利益相关者的要求

该企业主需要有什么样的系统,工作流程和业务规则,使他们能够有理解他们已同意战斗的机会一个清晰的概念.如果他们是规范的唯一主要受众,请专注于用户界面,屏幕工作流程以及业务和数据验证规则.

开发人员需要数据模型,数据验证规则,部分或全部用户界面设计以及对预期系统行为的足够描述,以便他们知道要构建什么.如果您正在为开发人员撰写文章,请专注于用户界面,在用户界面中映射到数据模型和规则.这应该比您自己进行开发时更详细,因为您在两个第三方之间的通信中充当中间人.

如果要指定两个系统之间的接口,则必须非常精确.

质量保证人员需要足够的信息来确定如何测试和验证应用程序的逻辑,验证和预期的用户界面行为.针对开发人员和QA人员的规范需要相当明确.

维护人员需要与开发人员相同的信息以及描述架构的系统路线图文档.

集成商需要数据模型并明确任何接口的定义.

规范的关键组成部分:

我假设有人正在为商业应用编写规范,因此下面的内容适合于此.其他类型系统的规格将有不同的侧重点.根据我的经验,功能规范的关键要素是:

用户界面:屏幕模型以及屏幕之间系统和工作流的交互行为的描述.

数据模型:数据项的定义和到用户界面的映射.用户界面映射通常在描述用户界面的规范的位中完成.

数据验证和业务规则:需要对数据进行哪些正确性检查,以及正在进行哪些计算以及定义.这里的例子非常有用.

接口的定义:如果您有其他系统可以使用的接口,则需要非常严格地指定这些接口.更简单的互联网RFC提供了非常好的协议设计示例,并且为界面文档的示例提供了良好的开端.明确定义界面并不容易,但几乎可以肯定会让你感到悲伤.

胶水:这是用例,工作流程图和其他相关工件帮助的地方.通常,详尽列出这些内容毫无意义,但系统中会有一些关键区域,这种类型的文档有助于将项目置于上下文中.我的经验是,选择性地包含用例和其他需求级别描述可以为规范增加清晰度和含义,但是为系统的每次单独交互编写用户故事都是浪费时间.

乔尔('软件'成名)写了一系列很好的关于这个名为无痛功能规范的文章,我在很多场合引用过这些文章.这是一篇非常好的文章,非常值得一读.在我看来,你的目标是清楚地解释系统应该以最小化歧义的方式做什么.将规范视为参考文档非常有用 - 各种利益相关者希望能够轻松查找的内容.

编写了一套关于规格的明亮点,明确的沟通部分比看起来更难.规范实际上是非平凡的技术文档,是对一个人的技术写作和编辑技巧的考验.您实际上是在编写描述某人应该构建的文档的业务.做好规格有点艺术.

做规范的回报是没有人想要做到这一点.正如您所写的可能是系统中唯一重要的文档,您可以发号施令.任何有议程的人都必须游说改变规范,或以某种方式对项目施加竞争规范.这是笔比剑更强大的一个很好的例子.

编辑:根据我的经验,关于"如何"和"什么"之间的区别的辩论往往是非常自私的.在任何非平凡的项目中,数据模型和用户界面将拥有多个利益相关者,而不是所有利益相关者都是系统的开发人员.在数据仓库中工作将使人们了解当允许应用程序数据模型成为免费的时候发生的混乱,而PFS应该让人们了解规范必须满足的潜在利益相关者.

有人拥有数据模型或用户界面设计这一事实并不意味着这些只是由法令决定 - 可以有一个话语和谈判过程.但是,随着项目变得越来越大,所有权和一致性的价值变得越来越大.过去我的观察是,了解优秀分析师价值的最佳方法是看到坏人所造成的损害.

根据我的经验,如果规范具有以下内容,那么它将有更多的机会被阅读:

尽可能使用图表 - 图片价值1000字

有一个标题页面,清楚地表明规范描述的内容

拥有整个文档中使用的样式.使所有标题具有相同的字体,大小和样式.使字体始终相同,使用相同的子弹样式等

不要浪费 - 要清楚简明扼要,不要添加额外的瑕疵来填写你的文件.如果一个点不能用几行文字解释,那么你可能需要进一步细分

我在公司里看到编写规范的人不了解系统.这几乎是通过编写规范来学习系统的一种方式.这通常以泪水结束......