3

我被要求（在我刚开始工作的地方）为一些新功能创建简单的规范，这些新功能将被添加到现有的注册系统中。我需要一点帮助，因为我以前从未这样做过。这是显示当前工作流程和新工作流程的两个图表。

我知道它们可能有点含糊，但这就是基本上正在发生的事情。我们正在向现有的 Windows 应用程序添加一个新的导入表单。我们正在通过添加一个搜索按钮来修改现有表单，该按钮将搜索搜索并填充由 ocr 读取的数据。

我是一名新开发人员，我一般不擅长编写文档，但我想改进这一点。也许一些关于如何编写这样的东西的例子会有所帮助。我搜索了一些示例，但我发现的大多数示例都是关于创建全新系统的。我需要一些东西来展示如何编写一个来修改现有系统。

这是我对规范的尝试。也许有人可以批评它。至少那时我会知道我需要改进什么。http://cid-ddb3f6a92ec2b97e.skydrive.live.com/self.aspx/.Public/Specs.docx

谢谢

4

4 回答 4

5

我喜欢编写规范（我在公司里很少见）。

图表是一个很好的方法，但对于更实际的想法，我从一个完整的规范模板开始，其中包含大量标题。对于一个新系统，您通常会对每个人说些什么。在您的情况下，您特别提到它是您正在修改的现有应用程序，但重点不是填写所有标题 - 重点是考虑它们，然后在适当考虑后将其删除。例如：

  • 业务需求（需求的简短提要，向业务、非技术用户解释）
  • 用例（通常仅适用于更大的规格）
  • 功能要求
    • 概述
    • 流程图等
    • 配置
    • 错误报告
    • 测试
    • 文档
    • 训练
    • 假设和附加约束
    • 第三方软件要求
    • 国际化
    • 可扩展性（例如，对于可能需要插入其他人的位等）
    • 定制
    • 问题（对于完成规范仍需要有人回答的问题）

此外，如果它真的是技术性的，那么您可能需要一个介绍部分： - 目标受众 - 术语 - 示例

除了最大的设计之外，所有这些通常都是矫枉过正的。但即使是修改，我也会仔细检查每一项，并考虑是否需要写任何东西。我认为这就是编写规范的许多价值所在——创建过程。换句话说，要做到彻底，不要错过太多。之后带来的所有好处——比如能够进行估计、能够向他人解释功能等——都是很好的副作用。只要它最终没有完全乱码，并且适合您的公司，我认为这比规范的具体外观、格式或内容更重要。

编辑：对您的规范的评论

我认为你在这里做得很合理。大多数开发人员应该能够接受规范并产生一些合理的东西，大多数业务分析师应该能够查看规范并弄清楚它的作用和工作原理。在我下面的评论中，请记住，在你想要规范的详细程度和你有多少时间之间总是需要权衡取舍。我倾向于相信规范越详细，每个人节省的时间就越多，但并不是每个人都这样。

  • 如果您希望业务用户（例如客户）清楚地理解这一点，那么“目标”部分可能包含一两句话来描述它所解决的问题。换句话说，不是它将实现什么，而是为什么。
  • 值得在这里明确命名中间临时表。至少这意味着如果有人在一年后回到规范，他们确切地知道在数据库中查找的位置。
  • 次要观点：根据我的经验，包含不切实际数据的屏幕截图更难理解。与其显示“我的示例表格”、“姓名”、“地址”等，不如使用一些合理的数据更容易理解。仍然可以伪造以保护客户的数据，例如“123 Fake St”等。但这并不是什么大不了的事。
  • 目前尚不清楚当出现问题时会发生什么。是否要检查临时表中的数据是否为有效格式？如果没有，用户是否给出了错误消息，或者以其他方式登录到某个地方？每行无效数据一个错误，还是整个批次一个错误？该表单由一个按钮组成——我认为我们可以同意这不是世界上最好的 UI，但我理解有时会发生这些事情——也许可以通过一个日志窗口来增强它以显示导入的结果。答案可能很简单，但开发人员需要知道它们是什么。
    • 取决于有多少数据，也许这不是问题，但如果有很多并且需要一段时间，那么有一个进度条可能是值得的。或者，提及数据是否将分阶段导入。
  • 值得一提的是数据移动到的永久表的定义吗？是所有字段都从临时表移动到永久表，还是仅移动一些？如果只有一些，你能显示什么映射到什么？如果永久表具有不同的数据长度 - 例如，如果Address Street是 Varchar(30) - 如果数据不适合会发生什么？同样，也许是简单的答案，但在这里会得到非常有用的答案。
  • 也许值得一提的是，数据是否将在单个事务中导入 - 如果数据导入中途失败，如果所有内容都回滚，或者导入的数据的一半仍然导入？
  • 如果另一个开发人员将做这项工作，我认为如果你为他们模拟/绘制屏幕，​​他们更有可能完成工作。即使它只是一个带有一个按钮的表单，即使我可以很好地猜测您的搜索弹出表单会是什么样子，如果我确切地知道它应该是什么样子，我就不会出错。Balsamiq Mockups 之类的工具（并在此处查看示例) 非常适合快速模拟，尽管默认的“comic sans”外观可能不适合经理。不过，我宁愿有一个肮脏的模型，也不愿根本没有。（注意：Balsamiq 的免费版本不允许您保存图像，但您可以通过导出/导入功能实现相同的目的。您也不能保存到 PNG 等图像文件，但您可以使用屏幕-捕捉程序来拍摄你所画的照片。）
  • 小点：我尽量避免使用“我”、“我们”、“我们的”等人称代词，只是为了让客户在必要时更专业地阅读。我只注意到一个“我们的”，所以你在这里的语气方面基本上是正确的。
  • 次要问题：varchars 是否足够，或者那里是否会有需要 unicode（即 nvarchar）的非标准字符？
  • It's less clear to me what's happening in the Voter Add/Update Form, but I don't have knowledge of your application - maybe everyone involved will say "oh right, I get it". For example I don't understand the relevance of "ImpRecord001" and "ImpRecord002" - would it be worth mentioning in the design what these batch codes actually mean in the real world?
  • Is the "Search Data" button the same as the "Search OCR" button?
于 2009-08-08T16:01:21.307 回答
3

对于任何文件：首先考虑你为什么要写它——谁会读它，他们需要知道什么？多少细节合适？另一个一般的想法

如果可能有用，那么请考虑一下您所写内容的信息来源。这样做的一个结果可能是您确保可以验证您所写的内容。例如，如果信息源是一个人，特别是对于 IT 文档，它可能是一个非 IT 人员告诉你的东西，那么你可能会非常小心你如何呈现一些信息，以便“源”也可以理解你是什么说。

还要仔细考虑当前文档之后的内容。例如，是否可以根据您编写的内容编写测试计划？这可能会导致您在很自然地扩展到测试用例的表格中呈现信息。

所以对于你的具体问题。“规格”是什么意思？您提供的工作流程不足以让用户查看并同意“是的，这就是我想要的”。一个人写一些代码是不够的。我想你可能需要几份文件。

1）。某种需求文档。您可能使用的一种格式是故事板。这侧重于用户可以看到和执行的操作。每个屏幕上显示的确切数据。如果显示的内容有计算基础，您可能需要有描述这些的附录。该文档可供用户和开发人员阅读。可以使用 Powerpoint 或 Word。

2）。从中您可能会得出一些明确的数据模型。逐项，逐字段。数据类型、大小、验证等。我可能会使用日期建模工具、UML 或电子表格。主要受众是开发人员，但理想情况下，用户（或业务分析中介）可以验证详细信息。[如果您没有业务分析师，您可能是业务分析师 :-) ]

3）。更多技术性的，参考项目 1 和 2 的开发人员的规范。实现的分解。模块、包、类或您正在使用的任何东西的名称。转换、算法和计算的定义。更技术性的文档。我会使用 UML，但任何精确的捕获形式都可以。这就是我们可能真正深入了解工作流程中某些详细框的含义的地方。

正如已经观察到的，通常我们还需要确保开发人员理解非功能性需求，例如安全性和数据量。在您的情况下，这可能会被隐含地理解，因此您现在可能不需要它......在其他生活中您可能需要它，因此至少有一个衬垫来提醒您未来可能是个好主意.

于 2009-08-08T08:44:52.603 回答
1

这些是规范的一个很好的开始。

我将通过创建您希望 Windows 应用程序看起来像的模拟屏幕截图来添加它们。

最重要的是，您可以添加每个数据字段的详细信息，以及允许的值是什么。

包括您能想到的任何异常的详细信息，以及您希望如何报告错误。

您可能还需要考虑需要什么样的报告和安全/审计，因为这些都需要包含在设计中。

最后，值得与开发人员坐下来讨论整个过程，完成每个步骤，因为我确信需要进一步的细节。

于 2009-08-08T08:36:18.863 回答
1

底部的一些步骤有点罗嗦。尝试将它们分开并确保单词 IF 永远不会出现。应使用菱形指定 IF，并根据条件拆分流动路径。

于 2009-08-08T08:43:12.217 回答