写作规范需要指导

Question

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

• 当前工作流程:http://img80.imageshack.us/img80/102/currentworkflow.png

• 新工作流程http://img245.imageshack.us/img245/6748/newworkflow.png

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

我是一名新开发人员,而且我在编写一般文档时非常糟糕,但我想对此进行改进.也许一些关于如何写这样的东西的例子会有所帮助.我用谷歌搜索了一些例子,但我发现的大多数都是在创建一个全新的系统.我需要一些东西来展示如何编写一个用于修改现有系统的东西.

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

谢谢

Answer 1

我喜欢写规格(我在公司里很少见).

图表是一个很好的方法,但对于更有文字意识的人,我从一个完整的规范模板开始,该模板中有大量的标题.对于新系统,您通常可以为每个人说些什么.在你的情况下,你特别提到它是你正在修改的现有应用程序,但关键是不要填写所有标题 - 关键是要考虑它们,然后在适当考虑后删除它们.例如:

• 业务要求(需要的简要概要,如业务,非技术用户所述)
• 用例(通常仅用于更大的规格)
• 功能要求
  • 概观
  • 流程图等
  • 组态
  • 错误报告
  • 测试
  • 文档
  • 训练
  • 假设和附加约束
  • 第三方软件要求
  • 国际化
  • 可扩展性(例如,可能需要插入其他人的位等)
  • 定制
  • 问题(对于某些人仍需要回答以完成规范的问题)

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

除了最大的设计之外,所有这些对于所有这些都是过度杀伤.但即使是修改,我也会仔细阅读每一项,并考虑是否需要写任何东西.我认为这是编写规范的许多价值来源于创造的过程.换句话说,试图彻底,不要错过太多.之后产生的所有好处 - 比如能够做出估计,能够向其他人解释功能等 - 都是很好的副作用.只要它不会完全乱码,并且适合您的公司,我认为这比规范的具体外观,格式或内容更重要.

编辑:评论您的规格

我觉得你在这里做得很合理.大多数开发人员应该能够采用规范并生成合理的东西,大多数业务分析师应该能够查看规范并确定其工作原理和工作原理.在下面的评论中,请记住,在您希望规范的详细程度和您拥有的时间之间总是需要权衡.我倾向于相信规格越详细,每个人都会节省更多的时间,但事实并非如此.

• 如果您希望业务用户(例如客户)清楚地理解这一点,那么"目标"部分可能包含一两句话来描述它所解决的问题.换句话说,不是它将实现什么,而是为什么.
• 值得在此明确命名中间登台表.至少这意味着如果有人在一年后回到规范,他们确切地知道在数据库中查找的位置.
• 小点:根据我的经验,包含不切实际数据的屏幕截图难以理解.而不是显示"我的样本表单","名称","地址"等,它可能更容易理解一些合理的数据.仍然是假的,以保护客户的数据,如"123 Fake St"等.虽然不是很大的交易.
• 当出现问题时,不清楚会发生什么.是否可以检查登台表中的数据是否为有效格式？如果没有,用户是否给出了错误消息,或以其他方式记录在某处？每行无效数据一个错误,或整个批次一个错误？该表单由一个按钮组成 - 我认为我们可以同意的不是世界上最好的用户界面,但我有时会理解这些事情的发生 - 也许它可以通过日志窗口来增强,以显示导入的结果.答案可能很简单,但开发人员需要知道它们是什么.
  • 也许这不是一个问题,取决于有多少数据,但如果有很多并且需要一段时间,那么可能值得拥有一个进度条.或者,提及是否将分阶段导入数据.
• 值得一提的是数据移动到的永久表的定义？是否所有字段都从登台表移动到永久表,还是只有一些？如果只有一些,你可以显示什么映射到什么？如果永久表具有不同的数据长度 - 例如,如果Address Street是Varchar(30) - 如果数据不适合会发生什么？同样,也许是简单的答案,但这些答案在这里非常有用.
• 也许值得一提的是,数据是否会在单个事务中导入 - 如果数据导入中途失败,如果所有内容都回滚,或者导入的数据是导入的一半？
• 如果另一个开发者会做这项工作,我认为他们是远更容易获得工作的权利,如果你嘲笑上升/绘制画面为他们.即使它只是一个带有一个按钮的表单,即使我可以很好地猜测你的搜索弹出窗口会是什么样子,但如果我确切知道它应该是什么样子,我也不会犯错误.像Balsamiq Mockups这样的工具(以及这里的示例)对于快速模拟来说非常棒,尽管默认的"漫画sans"外观可能与管理者不太匹配.我宁愿拥有一个肮脏的模型,而不是根本没有.(注意:Balsamiq的免费版本不允许您保存图像,但您可以通过导出/导入功能实现相同.此外,您无法保存为像PNG等图像文件,但您可以使用屏幕 - 捕捉程序来拍摄你画的东西.)
• 小点:我尽量避免像"我","我们","我们的"这样的人称代词,只是为了让它更专业,更好地让客户在必要时阅读.我只注意到一个"我们的",所以你在这里的音调大多是正确的.
• 小点:varchars足够多还是会有非标准字符需要unicode(即nvarchar)？
• 我不太清楚选民添加/更新表格中发生了什么,但我不了解您的申请 - 也许每个参与者都会说"哦,对,我明白了".例如,我不理解"ImpRecord001"和"ImpRecord002"的相关性 - 在设计中值得一提的是这些批次代码在现实世界中的实际意义吗？
• "搜索数据"按钮与"搜索OCR"按钮相同吗？