软件开发需求文档案例

这是4部分系列的第2部分。 第1部分：为什么“现实世界中的软件需求很难” 讨论了开发需求的挑战以及好的需求。 这篇文章着眼于需求开发过程及其在实际项目中的输出。

TL; DR

优先考虑运输软件以引出实际需求的敏捷方法与优先考虑先期需求工程的瀑布方法之间的熟悉的二分法过于简单。 在这些极点之间，存在一种用于开发需求的中间方法，该方法易于实施，并且可以更好地为用户和利益相关者带来价值。 这种方法的功能和优点包括：

• 定义一个迭代的需求开发过程，生成标准并达成一致的输出，并与更广泛的敏捷交付方法集成
• 利用廉价的实验（例如快速原型制作）以循证的方式快速进行，而无需交付功能全面的软件
• 使用层次结构（通常与需求工程相关联）在适当的抽象级别为用户和涉众提供有用的上下文
• 选择性地填充层次结构（不一定是自上而下的），以便开发团队和其他人员拥有他们需要的背景，以便进行调整并做出更好的决策。

视觉教练

Vision Coach是我将用作该主题的一种实际项目。 这是我的团队与拜耳医疗保健合作建立的一个平台，用于患有糖尿病性黄斑水肿 （DME / DMO）的眼病患者和医生的治疗。 DME影响全球约2100万糖尿病患者，并且是工作年龄成人失明的主要原因。

拜耳医疗保健提供的一种疗法是眼科医生用来改善患有DME等视网膜疾病的人的视力的一种疗法。 尽管存在视力障碍的情况，但是患者对治疗的依从性差，这意味着视力结果通常不是最佳的。 解决该问题成为该项目的重点。

为简便起见，我始终使用传统术语，例如“需求，启发，规范”。 尽管并不完美（将假设称为“要求”很奇怪吗？），但它们具有熟悉的优势。

需求方法

关于如何满足需求的争论通常集中在我称之为分析瘫痪和迭代崇拜的两种对立的方法上。 分析瘫痪说，您必须在任何编码开始之前就预先提出并指定需求，它们必须具有一组完美的属性（一致性，缺乏歧义性，完整性等），如果这需要花费数周甚至数月的精力，就这样吧。

迭代崇拜则相反-得出需求的最佳方法是构建某些东西并与用户进行测试。 用户不知道他们想要什么，或者至少不能总是清楚地表达出自己的想法，直到向他们提供工作软件后，他们的真正需求才出现。 因此，预先规范是浪费时间。

从广义上讲，这描述了需求开发的瀑布式和敏捷方法。 两者是相反的，通常假设您是站在另一侧。 那你站在哪一边？

好吧，显然您并不处于Analysis瘫痪状态 。 花费大量时间从利益相关者那里获取需求，使它们在开始编码之前是一致的，完整的，可测试的（以及其他所有需求），在面对不确定性和变化的情况下是徒劳的，而成功完成的一切只是增加失败和学习的成本。

像大多数团队一样，如果您需要失败并学习很多东西，那就不好了。 哦，事实证明它行不通-Standish Group的Chaos调查是经常被证明的一种来源。

这意味着您处于迭代崇拜方面，对吗？ 嗯，不，至少不是因为这里已被描述（或讽刺？）。 这种方法也有问题。 首先，如果没有第一个交付给用户的软件就无法说出任何与需求有关的宝贵信息，这是完全不对的-使用线框图工具进行快速原型制作是一种能够在编码开始之前为需求提供有用证据的技术。

其次，迭代实际上并不便宜-当然，它们比提供软件瀑布式样式便宜，但与快速原型制作等技术相比，它们仍然昂贵。

第三，如果您真的不花时间来定义需求，那么您构建的内容可能会离目标更远，因此需要进行更多的迭代才能达到目标。

我们的方法介于两者之间-预先结合了一些规范，并早日附带了工作软件，以在更高保真度的实验中引起用户的进一步要求。

流程和层次

在第1部分中，我确定了需求开发流程及其输出的一些关键属性-例如，它需要协作，迭代，并且需要针对不同的受众量身定制其输出。 除此之外，定义流程和确定用于优化输出的技术将很有帮助。

图1显示了我们遵循的过程。 它包括四个活动：

• 启发 -使用各种技术从用户和利益相关者中提取需求
• 分析 -了解要解决的基本问题，完善用户和利益相关者的要求，并将其与系统要求结合
• 规范 -使用层次结构和约定的模板制定需求，并记录下来
• 验证 -验证要求的准确性与所提供证据的准确性一样，一旦实施便可以验证。

图1 。 需求开发流程（改编自Wiegers＆Beatty， 软件需求 ，第三版）。

该过程是反复进行的，涉及经常在同一会话中在不同活动之间来回移动，这意味着更快的反馈循环和更好的输出。 它还涉及客户利益相关者的审核和批准决策点，这是开始任何编码之前所必需的。 除此之外，它还集成到了我们用于交付项目的更广泛的Scrum流程中，包括2周的冲刺，每日站立，在冲刺结束时进行客户展示和回顾，以及在下一个开始时进行计划。

此外，我们定义了一个层次结构，该层次结构由图2中所示的级别组成。

为什么要定义层次结构？ 不同的人需要在不同的抽象级别捕获不同的信息。 在Vision Coach上，客户利益相关者花了一些时间检查视觉，范围，用户故事和高级功能，但对技术设计或任务不感兴趣。

交付团队还需要决策的上下文，明智的层次结构可以提供决策的上下文。

图2 。 需求层次结构。

定义层次结构是容易的部分。 填充它比较耗时，但是考虑到我们不在分析瘫痪游戏中，并且只有一个小团队，因此填充的数量仅是我们前进所需的数量。 最初，这涉及在愿景和范围级别进行更多的工作，以使项目获得绿色，然后在较低级别进行。

重要的是，我们并没有始终从上至下填充层次结构，这是一个很好的例子，即范围的更改，如果我们的用户故事和任务符合现有功能和非功能性要求并且没有足够的争议性或复杂，需要技术设计。

也就是说，我们将层次结构更多地用作指导而非可强制执行的架构-当我们需要在适当的抽象级别上生成需求时，它可以帮助我们构造需求。

启发

医疗保健很复杂。 有很多利益相关者，通常以复杂的方式联系在一起。 这些包括患者，医生，诊所，医院，付款人，监管者……清单很广。 与所有人直接接触是不切实际的，因此您要创建代表代理，这就是我们在这里采用的方法。

需求和约束（置于需求上的条件）来自大量利益相关者群体。 这里是主要的（还有其他！）：

用户数

• 患者 。 患者通常处于工作年龄（55岁或以上），已经患有糖尿病多年，并且随着疾病的发展开始出现DME等并发症。 与该小组的直接互动受到严格法规的约束（稍后会详细介绍），这使用户测试比平时更加​​困难。
• 医生 。 这些医生是眼科医生（专科眼科医生），他们与其他医生，技术人员和管理人员在独立诊所或医院内诊所中的其他医生，技术人员和管理人员团队一起工作，既有公共场所也有私人场所。
• 诊所和医院 。 医生治疗患者的组织。 较大的组织具有完善的公司职能，例如IT，临床治理和信息治理，所有这些都有需求。

客户端功能

• 市场营销 。 全球眼科营销团队委托并管理了该项目。 他们有与业务优先级和证据使用（定性和定量研究）有关的要求，以指导我们的工作。
• IT 。 政策和程序中记录的业务规则规定了工作方式，有时还要求使用特定技术。 要求涵盖了诸如设计准则，Cookie，用户同意，Web分析和证书管理之类的内容。
• 安全性 。 系统存储可识别的患者数据，这些数据需要严格的控制。 安全要求被提炼为供应商安全评估。 另外，我们收到了有关外部笔测试，使用指定供应商的分布式拒绝服务（DDoS）保护以及针对信息安全的ISO27001标准认证的要求。
• 合规性 。 Vision Coach必须经过法律，医学和监管（LMR）符合性审查，然后才能被患者和医生使用。 这涉及针对这些不同领域的要求进行全球和本地审核。 评论通常会引起新的要求。

客户供应商

• 翻译社 。 该机构将全球英语副本翻译成12种翻译和本地化版本，对所使用的技术和流程有要求和约束。

我们

• 交付团队 。 我们是一个小团队，担当许多角色：开发人员，测试人员，DevOps，技术架构师，产品所有者（PO），项目经理，用户体验（UX），UI设计和临床领域专家。 PO和UX潜在客户提出了要求。

对于客户，我们在全球范围内创建了一个核心团队，代表整个企业的关键客户职能。 我们从该小组中提出了要求，如果我们需要与其他利益相关者（例如，医疗器械法规或数据隐私等领域的专家）进行交流，则可以通过此团队来促进。

对于患者和医生而言，诱因变得更加复杂，因为制药公司（及其供应商）受到严格的法规和与他们进行沟通的内部流程的约束，这意味着用户测试并不容易，快速或便宜。

幸运的是，首先，我们可以在内部获得临床专业知识，并且能够依靠广泛的市场研究和对先前具有相似原型的患者进行用户测试。 在持续的基础上，我们通过观察，访谈，讲习班，使用原型进行测试（针对不同的保真度构建）和临时跟进来提出需求。

分析，规范和验证

采购结果由PO和UX主管记录，通常一开始通常是非结构化注释，然后回放给客户利益相关方进行审核和批准。 然后，这些由PO整理，并转换为用户故事（在我们的层次结构中为2级），并使用商定的模板记录在Jira票证中，其中包括：

• 敏捷的用户故事，形式为“作为[用户类型]，我想要[某些目标]，以便[某些原因]”
• 解释要求为何如此重要的背景/理由
• 使用Gherkin的步骤语法接受标准，涵盖主要目标和替代目标
• 链接到线框，UI设计和其他相关工件。

与内部交付团队的讨论始于积压的改进会议，其目的是改进故事，确定接受标准，并通过功能，非功能性要求，技术设计和任务来增强它们（级别3-5）。

讨论在计划中结束了，我们在其中编制了一份冲刺积压的需求清单，以满足我们的“就绪定义”。 通常由于复杂性而引起的对技术设计的分歧是进一步设计工作的线索，我们在sprint期间的设计会议上做了这些工作。

在所有这些会议中，PO在适当的领域专家的支持下，代表用户和客户利益相关者代表开发人员，帮助他们回答问题并指导他们的决策。

这是我们在层次结构中的3-5级上指定工件的方式：

• 在Jira史诗中高层捕获了功能和非功能需求 （NFR；级别3），并附有简要说明以及与线框，设计等的链接，并用于对相关的用户故事进行分组。 我们使用与技术设计相同的方法将NFR记录为单独的文档（请参阅下一个项目符号），并在用户案例中使用了接受标准来帮助他们尽早浮出水面。
• 技术设计 （第4级）由散文和图表组成，并记录在reStructuredText和PlantUML中，存储在git repo中，并使用Sphinx和Read the Docs主题呈现为静态html，并带有在我们的文档中创建的托管文档的链接。吉拉项目。 如今，我们已经大大改变了文档堆栈，但是我们仍然非常喜欢文档编码方法 。
• 任务 （第5级）在Jira中被记录为用户故事父票证的子任务，通常采用范围内和范围外的工作清单的形式。 这增加了故事的接受标准的粒度，使我们能够验证故事是否已完成（过程中验证步骤的一部分）。

范例要求

让我们看一下从为患者移动应用程序入职以来层次结构的垂直纵断面，看看输出结果如何。 它包含了适用于全球平台以及仅适用于患者应用程序入门的各种内容。

视野和范围（1级）

我们用这个 简洁的模板（最初来自Geoffrey Moore的Crossing the Chasm），以简洁地捕获视觉和范围：

• 对于糖尿病眼病患者（ 目标用户 ）
• 谁通常不坚持治疗（ 需要或机会的陈述 ）
• 远景教练服务（ 产品名称 ）
• 是移动应用（ 产品类别 ）
• 这提供了对关键健康数据的访问，有助于理解数据以及采取措施改善依从性，视力结果和总体健康的工具（ 关键优势 ）
• 与其他针对糖尿病患者的应用不同 （ 主要竞争替代品 ）
• 除了潜在的糖尿病外， 我们的产品还解决了糖尿病眼病（ 原发性分化的陈述 ）

用户案例（第2级）

入门史诗将所有用户故事收集在一起进行入门，其中包括两个独立的流程-注册和登录。 图3显示了两个流程中的故事的屏幕快照-基于SMS的一次性密码（OTP）验证。 它使用上述模板，并具有涵盖主要目标和替代目标的接受标准。

图3 。 在注册过程中用于帐户验证的示例用户案例

功能和非功能要求（级别3）

特征

入门功能是在Jira史诗中捕获的，作为单独的注册和登录流程的列表。

注册：

• 确认地区和语言
• 同意条款和条件
• 输入电话号码
• 验证短信一次性密码（OTP）
• 输入用户名
• 确认治疗计划

登录：

• 输入电话号码
• 验证短信OTP

图4所示的准活动图对此进行了补充，并链接到相关的用户故事。

图4 。 耐心的移动应用程序入职流程。

非功能需求（NFR）

• 安全性非常重要，因为该系统存储患者数据，这是GDPR定义的敏感个人数据类别。 更广泛地说，我们被要求遵守和认证ISO27001，这是信息安全的行业标准，其中一部分涵盖了用户身份验证的控件。 这需要大量的努力，并且影响了我们的技术设计和实施，以及我们的流程，人员和位置。 共同商定的审核员正在进行的年度审核也意味着这不是一次。
• 国际化（i18n）和本地化（l10n）很重要，因为该应用程序最初设计用于具有12个本地副本集的10个国家/地区。 还有一个项目要求，由认可的翻译机构进行所有翻译工作。 与产品相比，最终影响过程更大。
• 鉴于源自法律，法规，标准和合同的有关患者数据的合规性要求， 法律非常重要。 在处理患者数据（出于真实和可感知的原因）时，数据主权（存储数据的国家/地区）很重要。 对于Vision Coach，患者数据需要生活在许多不同的全球区域中。 入职时捕获的可选分析数据共享同意书也需要至少每年存储和更新一次（符合欧盟法律）。
• 考虑到某些用户的视力障碍（从轻度到重度）， 可访问性很重要。 对此的一个限制是iOS和Android原生提供的丰富的可访问性工具，以及一些证据（公认的是，在更广泛的人群中），这些工具经常被视障用户（例如屏幕阅读器）使用，如图2中的接受标准。 3）。
• 性能和可伸缩性很重要，因为系统需要在最短的时间内做出响应才能使用，因此，我们部署基础架构的方式需要能够支持用户数量的最佳情况估算，尤其是在负载很重的情况下。

技术设计（第4级）

• 身份验证 。 图5显示了用于广泛认证流程的UML序列图，包括使用基于SMS的OTP进行电话号码验证。 我们没有为该应用程序生成许多时序图，但是在这种情况下，身份验证流程是我们要做的一个领域，因为在技术设计上存在分歧。 如前所述，分歧和复杂性通常是触发我们在技术设计会议上进行更多工作的诱因，而顺序图和其他图则偶尔会作为这些结果的输出，当被认为对分析需求和改善团队协调性很有用时。
• 

图5 。 UML序列图显示了端到端认证流程

• I18n和l10n 。 由于翻译工作是由外部机构完成的，因此翻译内容的格式必须易于在此过程中来回移动。 我们决定对构成Vision Coach的各种应用程序使用通用框架。 所有内容都存储在yaml文件中，这些文件已从任何单独的应用程序中分解出来并在运行时加载。 对于患者应用程序，在启动时，该应用程序将从翻译API加载内容。
• 用户同意 。 作为服务同意条款的一部分，要求用户同意跟踪应用程序的使用。 我们需要记录同意事件，并将其发送给客户端的IT涉众指定的第三方API。 然后需要将同意信息提供给多个应用程序和设备，这对于患者应用程序是通过存储在经过身份验证的API中的数据来完成的。
• 短信服务 。 我们选择使用Amazon Web Service（AWS）的简单通知服务（SNS）发送事务性SMS消息。 鉴于该应用程序托管在AWS上，因此这是一个方便的决定。
• 区域部署 。 由于需要将患者数据保留在某些区域内，因此我们需要将该平台部署到多个AWS区域。 这为改善全球客户的延迟带来了额外的优势。 仅需要一个版本的患者应用程序，并且我们使用了众所周知的单个全局端点来允许其发现API和身份验证服务等区域资源。 图6显示了区域部署。 它包括一个托管静态服务的主要区域（EU），以及托管API服务（由AWS Relational Database Service（RDS）和基于HL7 FHIR标准的临床数据存储库支持）的单独区域和身份验证服务。 移动应用从主要EU环境中的配置服务获取有关适当区域的位置（基于电话的区域设置ID）的配置数据，然后从适当的区域环境获取其数据

图6 。 视觉教练区域部署

• 高可用性部署 。 应用程序使用水平很难预先预测，这是我们部署在AWS的Elastic Container Service（ECS）上的部分原因，因为它使我们能够在需要时轻松扩展应用程序，并且尽管成本高昂，但仍可控制成本区域设置。

任务（5级）

实施工作记录在Jira父票证附带的子任务中。 通常，我们从最小的可行产品（MVP）开始采用增量方法实施，然后从那里分层功能。 遵循电话号码验证的故事，前端和后端（FE＆BE）任务包括：

• 基本OTP输入框（FE）
• API调用以验证OTP验证完成（FE）
• UI控件导航到上一屏幕（FE）
• 一旦提供了真正的API（FE），便可以进行其他集成工作
• 为前端开发人员实现模拟API终结点，以尽早开展工作（BE）
• 实现真实的API端点，以根据数据库（BE）中存储的值验证OTP

超出MVP的增量包括以下任务（FE＆BE）：

• 在验证码中输入最后一位数字时自动提交OTP
• 在OTP验证时自动路由到入职的下一个屏幕
• 在交付失败的情况下重新发送OTP

挑战与解决方案

使用此处勾勒出的方法，我们在开发和管理需求方面遇到了许多挑战。 这些是主要解决方案，也是我们的一些解决方案：

• 潜在需求 。 用户和客户利益相关者常常不知道他们想要什么，以为他们知道他们想要什么（但不是真的），想要他们假设别人会知道的事情……这是您的工作，找出这些要求然后建立东西满足他们。 最好的方法是在实际环境中将工作软件交付给具有代表性的用户样本，但是由于拥有完整的跨职能团队的迭代成本很高，因此我们可以使用快速原型技术来获得有用的信息（尽管（当然较弱））以较低的成本尽早提供反馈。
• 合规和用户输入 。 与患者和医生的所有互动都必须通过合规性计划（记录，审查，批准）（法律，医疗和法规），因此既不快捷也不容易。 每当我们需要用户反馈时，我们都必须制作一个讨论指南，其中包含所有屏幕的PDF，以供相关的本地合规团队审阅。 这使开发过程中的用户交互比我们希望的要少，但并非不可能。 我们通过创建可循环使用的模板作为讨论指南来解决此问题，并将PDF生成内置到我们的自动化端对端测试套件中，从而使审核所需的资产的生产更加容易。 这有助于加快将我们的软件展示在用户面前的时间表。
• 企业发展缓慢 。 企业中的所有事情进展缓慢。 这意味着迭代开发可能会很慢，并且需求通常处于不同的准备状态。 有几件事情有所帮助：（i）制定了实施计划，以便在需要更多时间的领域进行澄清和验证；（ii）首先开发具有更好开发要求的功能； （iii）确保我们不会为我们无法控制的流程部分承担任何风险。
• 企业不是敏捷的 。 企业通常不敏捷，而医疗保健企业当然不是。 但是，我们的项目负责人被吸引到了新的工作方式，因此我们在每次冲刺结束时将全球范围内的客户评论和反馈嵌入到展示柜中（更频繁的交互/决策是不现实的）。 这很好地在整个项目中引发了其他客户需求。 主要的挑战是在发布之前要进行合规性审查，这是在（接近）最终资产上完成的本地流程，并且不能进行迭代工作，这意味着交互和必备需求在周期的后期出现。 这个过程是不可更改的，因此，实际上我们唯一可用的解决方案是在交付计划中建立应变性。 事实证明，这种偶然性是不够的，尽管我们能够触发合同延期，这至少可以使我们最小化财务方面的损失。
• 利益相关者很多 。 对于资源有限的小型团队而言，征集遍布全球的众多利益相关者的要求是不切实际的。 我们通过在全球范围内创建核心团队来解决此问题，该团队的职责是代表整个企业中利益相关者的需求，并在必要时促进与他们的联系。 我们已经与我们的团队和流程安排了接触点。 这在许多领域都做得很好，但是当然不是完美的，需要额外工作的主要领域是合规性，各地的情况大不相同。
• 用户故事还是用例 ？ 用户故事为我们提供了一种描述用户需求的简洁方法，并且利益相关者可以理解。 他们也有缺点，其中有许多是由阿利斯泰尔科伯恩在突出很大一块用户故事与使用情况的限制，即缺乏对设计师（I）的背景下，（II）为完整开发团队及（iii）粒度用于计划/研究。 用例虽然可以填补这些空白，但它们也更难编写，也让利益相关者难以理解。 我们决定结合每个要素-以接受标准为核心的用户故事，以及替代目标（例如扩展点）和UML图（例如，使用PlantUML的人类可读语法而不是XML）的接受标准，以提供技术设计的上下文和粒度以便及时评估。
• 范围蠕变 。 这在所有项目上都会发生。 当然，我们为此内置了应急缓冲，这为预算范围内的范围增加提供了一些余地。 在这个特定项目上，很多范围的爬升都来自本地合规团队，尤其是在要求更高的国家（例如英国和加拿大）。 由于这些要求通常以解决方案的形式提交给我们-常常与为满足患者或医生而实施的解决方案相冲突-我们首先花时间确定基本要求，然后研究如何以一致的方式满足这些要求与其他用户要求。 有时这是可能的，而其他时候则没有，合规性才是关键。

加起来

尽管您在网上阅读的有关需求开发的许多内容都表明， 分析瘫痪和迭代崇拜之间存在两极分化，而且大多数人都与后者相吻合，但是中间的方法可以Swift产生真正的收益。

就我的金钱而言，这种中间方法（此处所述方法）的最大实质好处是，由于更好的环境而改善了决策，从而提高了速度，现金消耗和团队士气。 从个人经验来看，由于花了一些时间思考和定义需求，我的团队的速度提高了约40％。

此“客观”度量带有一些警告-它是通过​​在确定更好的需求开发引入之前和之后，在定义的时间段内测量每个sprint完成的平均故事点之间的差异来粗略地计算得出的，并且它无法控制其他混杂变量（例如人事变动）。

但是在方向上这很有趣，而且它在主观指标上也得到了极大的改善，即团队士气和对冲刺过程中取得的进展的满意，这一事实提供了一些其他证据。

总而言之，时间和精力的初始投资所带来的投资回报是可观的，投资回收期可以短于单个冲刺，因此绝对值得这样做。

下次我该怎么做？ 缺少想出一种使合规功能完全敏捷并与开发周期完全集成的神奇方法，我要做的主要事情是：

• 提出在开发周期中更早地让本地合规团队参与的可接受方法，例如，通过让更多的人参与原型审查以及早淘汰相关要求
• 找出如何以更一致，更可衡量的方式捕获非功能性需求，并通过诸如Planguage之类的形式主义来寻求灵感
• 使用不同的工具链来管理需求-使用Jira和静态网站的组合来处理文档存在很多问题，我将在下一篇文章中介绍。

下一步是什么

第3部分重点介绍用于管理需求的工具。 它包括对我们过去使用的工具的分析和评估，其他现代软件团队在决定如何管理其需求时往往会了解和考虑。

参考书目

• A. Cockburn， 编写有效的用例 ，Addison-Wesley Professional，2000年
• A. Cockburn， 为什么我仍然使用用例 ，2008年
• D. Gause和G. Weinberg，《 探索要求：设计之前的质量》 ，多塞特郡出版公司，1989年
• D. Leffingwell， 敏捷软件需求 ，Addison Wesley，2010年
• G.摩尔，《跨越鸿沟》，第三版，《哈珀商业》，2014年
• K. Wiegers＆J. Beatty， 软件要求 ，第三版，Microsoft Press，2013年

特别感谢Karl Wiegers的有用评论！

翻译自: https://hackernoon.com/foo-xv1x3278

软件开发需求文档案例