如何编写高效的规范？

Question

我见过不同的程序经理以不同的格式编写规范。几乎每个人都有他/她自己的写作规范的风格。

一方面，给予程序员的那些冗长的文件可能会导致他/她遗漏一些东西。我个人害怕文件规格......我认为这是因为我的阅读风格......我总是快速阅读我认为会让我错过关键点的事情。

另一方面，我已经看到了我们的一位客户用Excel编写的这些创新规范。他以前编写规范的方式是在Excel中创建一个模拟应用程序并使用一些VBA来模拟它。他会做一些事情，比如按钮点击表单应该去哪里或应该执行什么操作（在评论中）。

在数据表单中，他会在单元格和每个数据输入单元格中显示一个表单，他会评论哪些有效值，它应该执行哪些验证等。

我认为使用这种技术，不太可能错过需要完成的事情。此外，为开发人员进行单元测试要容易得多。测试人员在实际编写之前对系统有了更好的理解。

Visio是另一种进行屏幕设计的工具，但考虑到VBA支持及其功能，我仍然认为Excel比它具有更好的优势。

你认为这应该成为一种更流行的编写规范的方式吗？我知道这涉及项目经理（或任何编写规范的人）的一些额外工作，但收益很大......我自己可以看到使用它可以获得很多生产力。如果有更好的规格格式可以帮助程序员。

Answer 1

Joel on Software特别擅长这些，并且有一些关于这个主题的好文章......

a specific case

Answer 2

两种方法对我来说都很有效。

一个是您在问题中描述的“工作原型”。根据我的经验，该公司与一位用户界面专家签约，以创建功能齐全的HTML模拟。页面上的数据是静态的，但它允许开发人员和管理人员查看和使用网站的“功能”版本。剩下要做的就是用动态内容替换页面上的静态数据 - 这个原型是我们产品初始版本的规范。设计者甚至在弹出对话框中包含了一些细微的解释，这些行为在将鼠标悬停在模拟链接上时会出现。它对我们的团队很有用。

在随后的项目中，我们没有UI专家的奢侈品，但我们使用了类似的方法。我们使用wiki来模拟网站的版本。我们在系统的功能方面之间建立了链接，并详细记录了每个功能。反过来，每个功能都可以链接到详细的设计和架构决策。我们还习惯使用wiki来保存每个版本的列表功能列表（这已成为我们的发行说明）。这些文档链接回详细功能页面。维基成为一个活生生的文档 - 非常详细地描述了我们系统的发布和演变。这是一个非常宝贵的资源。

我更喜欢wiki和工作原型，因为它更易于扩展 - 随着系统的发展而不断增长并变得更有价值。

Answer 3

我想您可能会看一下测试驱动需求，这是一种制作可执行规范的技术。

为此目的，有一些很棒的工具，例如FIT，Fitnesse，GreenPepper或Concordion。

Answer 4

其中一本Microsoft Press书籍提供了各种文档的优秀示例，包括SRS（我认为这就是您所说的）。它可能是Weigert的要求书之一（我认为这是他的名字，我现在正在对它进行消隐）。我看到美国政府组织将其作为一个模板，从我与政府的三次工作经验中，他们喜欢尽可能地自己创造，所以如果他们重复使用它，那一定是好的。

另外 - 在我看来，规范应该包含NO CODE。它应该关注系统必须做什么，应该做什么，不能使用文本和图表。