大家好！ 我叫Denis Oleynik，我是1Service的技术总监。
在我们公司中，我们花费大量时间来处理需求。 随着经验的积累，我们开始意识到开发软件产品中常用的工具将我们带入一种状态，即不能说我们确切地意识到了客户希望我们提供什么。 正是因为在某些时候，它们的软件实施和后续测试中最初收集的需求之间存在差距。
这条线介于Confluence中记录的需求和Jira中实现这些需求之间。 在测试工具中的测试用例与Confluence中的相同需求之间还有另一条线，即关注与Jira中的任务相关的代码。 对于以下问题缺乏明确的答案：“我们为什么/为什么要这样做”或“我们做了客户想要我们做的所有事情”，这引起了我们的热烈关注。
在某种程度上，在我们看来，“文档就是代码”（文档即代码）的概念将使我们能够找到这些问题的答案。 “文档就是代码”的概念假定我们以简单的文本文件的形式存储需求，体系结构解决方案，用户指令，这些文本文件可以使用
（D）VCS类系统进行版本控制，理想情况下，输入输出数据模型也应存储在一个平面中。文字形式。 实际的“可读”文档（以及可执行模块）将作为项目组装的结果出现。 在这种情况下，技术文档将与整个项目的开发一起以相同的代码版本控制原则进行开发，这将使其能够满足端到端可追溯性，验证和相关性的标准。 同样，这种方法从本质上解决了组织所谓的“需求的基本版本”（基准）的问题，对于许多需求管理系统而言，这成为一个实际问题。 特别是，在Confluence中，建议通过创建需求的原始空间的副本来解决此问题，同时失去需求的任何联系和遗传。 实际上，本文致力于在我们公司中对该概念进行现场研究。
背景知识
我们认为，阻止这一概念在大众中广泛使用的原因是，用于以平面文本形式直观表示和管理需求的工具非常糟糕。 这意味着您不会显示平面文本文件“产品负责人”，这样他就可以在其中看到“项目范围”，您无法在演示页面上为利益相关者显示文本文件，他们在编辑阶段没有图形，图表和图片-这已经使业务分析师感到厌恶本质上应该产生内容。 而且只有开发人员才会高兴和大喊：“酷！ 只有铁杆！ 更多犯法！”和其他异端。
还有另一个相当微妙的地方。 出于某种原因，“文档即代码”概念的辩护者确保文档一旦位于存储库中的代码旁边，这将导致其强制改编并与代码更改同步，从而使代码保持最新（
第1.2.1节）。 ） 但是我们认为，这一刻仍将是一个纪律问题，因为没有人会去更改代码，文档也不会更改。 也就是说，文档与这种概念的实现的相关性留给开发过程的管理，其中发布之前的强制性步骤是“检查文档的相关性”。 在这种情况下，如果您在编译生成的文档方面没有考虑某些自动化操作，则“文档就是代码”离Word文件并不远。
好吧，是的-首先，它“不方便，令人爱戴，干燥”，其次，技术芯片“用布盖住了”更新文档的问题。 有一个常见的刻板印象：“我们是ajail的人-但我们不需要ajail的文件！” 坦率地说，这并非完全正确。 我想通过比较Karl Wigers的出色著作“软件需求开发” [4]中的用例和用户案例方法来驳斥该错误。 如果我们将基于用户故事的开发方法与敏捷方法相关联，那么Wigers会以这种方式根据用户故事来制定需求的演变：
用户历史记录→（讨论）→更新了用户历史记录（带有接受标准）→（讨论）→验收测试
（第169页，图8-1）。 因此，由于敏捷开发项目中初始需求的演变而产生的输出文档就是验收测试。 如今，一种用于组织验收测试的相当普遍的技术是使用以
Gherkin语言[5]编写的测试脚本，这些脚本存储在所谓的特征文件（简单文件，文本文件）中。
因此，为了
支持在敏捷开发项目中实现“文档就是代码”的概念，我们需要一个工具，该工具将伴随着需求从用户故事格式到验收测试的演进，随着需求的成功执行，这些工具将生成相关的文档。 不幸的是，迄今为止，尚不存在能够完全支持该过程（或至少假定其希望支持该过程）的工具。
研究工具架构
因此，没有工具，但是我想探索这个概念。 从绝望中，我们不得不发展它。 如果已经存在这样的工具（我们将其称为StoryMapper），那么它将具有什么样的体系结构，以便以最小的压力毫不干扰地集成到开发过程的现有生态系统中？ 如果这已经是一个完整的开发过程，则
CI / CD循环可能已经在其中运行，并且肯定会使用版本控制系统（很可能是基于git的版本）。 在这种情况下，下图显示了StoryMapper在开发过程中的位置：
图 StoryMapper工具在开发过程的结构中的位置1因此，StoryMapper将直接与git存储库的托管服务以及
CI / CD循环进行交互。 需要与git托管服务集成，以获取功能文件的当前集合（如果有的话），并将更改结果放入功能文件，与结构化文档有关的服务文件，将输入和输出数据的示例返回到存储库等。 。等与轮廓
CI相互作用
/ CD需要能够运行组件场景测试（手动或计划），并且用于随后的测试结果-用相应的特征文件与它们匹配（例如OBRA 个将被核实和检查的文档相关性）。
您必须了解，StoryMapper几乎不必声称“还有另一个小黄瓜编辑器”的标题。 是的，应该规定编辑特征文件的基本功能，但是我们清楚地知道，如果
BA或
QA选择了VSC，Sublime，Notepad ++甚至是vi（为什么不这样做），那么就说服它们仅在StoryMapper中满足要求。任务不是那么忘恩负义，而是不正确的。 因此，我们假设应该考虑使用StoryMapper的可能性，尤其是：在您喜欢的编辑器中开发功能，而StoryMapper用于构造现成的功能文件。 在研究方向部分中将对此进行更多介绍。
最低要求的功能
由于StoryMapper当前处于MVP状态，因此这是我们为此制定的最低要求，以便可以真正开始使用它：
- 基于Git的故事映射；
- 小黄瓜编辑
- 启动方案测试的程序集（手动并根据时间表）；
- 在用户故事地图上反映方案测试的结果。
因为本文的主题是手术过程，而不是外科医生的手术刀，所以我不会详细介绍该工具的功能。
研究领域
主要思想是：
如果使用“文档就是代码”的概念，而您在编写代码时没有脱离客户的要求而编写某种任意文档，那么这些文档将消失，并且变得与MS格式的文件版本无关紧要。字词 因此，我们想考虑和探索在整个开发周期中使用该概念的选择。 另一方面，我们也对团队不使用“文档就是代码”这一概念但希望应用它的过渡时刻感兴趣–在这种情况下该如何采取行动？
因此，StoryMapper是一个工具，它并不能管理唯一的真实用例。 相反，每个潜在用户都可以看到他们使用该工具的选项。 我们专注于三个主要领域：
- 灵活的开发：从故事图到验收测试；
- 构建和可视化功能文件的集合；
- 生产力监控。
下面我将详细描述我们在各个方向上取得的成果。
灵活的开发：从故事卡到验收测试
这个方向涉及新产品的开发或现有产品的改进。 在这个方向上的工作是以代号“ BDDSM”进行的：结合了故事映射技术和
BDD开发方法。 它扎根了。
因此，对于初学者来说，将为功能文件创建一个git存储库，并在其中分配一个分支以与StoryMapper进行交互。 在StoryMapper中创建了一个项目，该项目已与将要从事该项目的业务分析师联系在一起。 与利益相关者进行沟通之后，业务分析师开始制定产品的共同愿景，并以用户故事图的框架[1,2]的形式对其进行修复，该图首先是
UF一级的草图：
图 6用户故事地图的上层框架（可单击）然后逐渐填充第二级用户活动：
图 7个用户故事图的第二级框架由于每张卡都是文本文件，因此无论是在收集要求阶段（如果卡是在与用户沟通的过程中编译的）还是在采访的后处理阶段，沟通的结果都将直接传输到
UF和
UA卡。 这是将需求进一步分解为用户故事级别的基础。
图 UF级别的8个Gherkin无语法要求文本接下来，业务分析师意识到如何将用户活动分解为用户故事，并在StoryMapper-
US中形成第三级地图。 隔离
美国与接受标准的制定有关，也就是说，如果“您作为某人想要某物”，那么我们将在您收到该事实后进行检查[3]。 初学者的接受标准也可以在
美国固定为纯文本。
在建立了接受标准并与利益相关者达成一致之后，业务分析人员将它们以Gherkin语言的脚本形式放置。 实际上，将文本“方案：KP-否”附加到每个接受标准，这将迄今为止的抽象用户故事转换为功能文件。
图 8.1用户故事作为小黄瓜上的脚本的接受标准之后，通过几种放大的步骤对每种情况进行解密，这些步骤揭示了将如何精确地检查特定的接受标准。 此外，这些步骤可以由开发人员编程，也可以从使用的Gherkin框架的步骤库中键入，然后导出到导出脚本。
同时，组织了一个测试台，组装服务器将在该测试台上运行功能测试，并等待带脚本的
美国准备就绪。 当实现接受标准的产品和方案准备就绪时，组装服务器开始以Allure和Cucumber格式发布报告并将其发送到StoryMapper，StormMapper依次将组装结果以Cucumber格式投影到用户故事地图上：
图 9包含脚本结果的用户案例图同时，StoryMapper提供了对产品准备情况的三个层次的理解：UF是显示正确运行的脚本（满足验收标准），处理错误且尚未准备就绪的脚本的顶层。 也就是说，实际上，最高级别是产品准备就绪程度的指标，也是尚待完成的工作量的指标（这是产品所有者的级别）。 较低的级别使您可以准确地找出存在哪些困难的用户活动，以及需要在哪里进行努力以使产品完成（这是Scrum管理员的级别较大，而产品所有者的级别较小）。 美国的最低级别是业务分析人员，开发人员和质量检查人员进行互动，共同开发利益相关者期望的产品的水平。
同样，在组装线的最后步骤之一中，将创建自动文档。 您可以与
同事一起阅读有关此内容的更多信息。 这不是唯一的选择，我们计划将
Pickles软件包包含在我们的工具中-这是“实时文档”世界中的事实上的标准。
结构化和可视化特征文件的集合
为此，我们考虑了这种情况。 在围绕BDD，功能测试和行业开发标准进行了大肆宣传之后，开发团队承诺编写功能文件。 突破荆棘，已经在存储库中积累了相当大的收藏。 但是，当您的收藏夹中有10个文件时，Allure格式的报告仍会提供一些可靠的产品状态图。 但是，如果功能文件的数量以数十个（有时是数百个）为单位，那么迟早您将需要以某种方式进行结构化。 首先想到的是将它们分类到主题文件夹中。 为了什么 通过利益相关者，通过元数据，通过子系统？ 这些绝不是闲杂的问题。 如果后来发现原来原本是按照上帝会将其写入灵魂的方式来编写功能文件的，并且同时存在与多个文件夹相关的脚本，那又如何呢？
因此，此用例意味着需要清理文档，以便从“功能分开，文档分开”切换到“文档是代码”。 当这样的存储库连接到StoryMapper时，所有功能文件都将落入UF0和UA0下的第一列。 结构化的下一步是组成结构的骨架。 在StoryMapper中，它们都是相同的
UF和
UA ，但是没有人坚持只从这个角度考虑它们。 可以将它们简单地视为2个层次结构，在此之下可以放置以前非结构化的特征文件。 设置结构后，将第一列中的特征文件拉到相应的
UA下 。 毫无疑问，此过程会引起反射和特征重构的攻击，因为当您拖动时，在其初始编写过程中发生的整个混乱的深度就变得清晰了。 有时足以将脚本从一个文件传输到另一个文件，有时将一个大文件拆分为多个文件以恢复语义连接，有时甚至只是将其扔进垃圾箱，因为古老的无法执行的手稿正躺在存储库中。
如果已经配置了组装流水线（好吧，因为有一个功能文件存储库，那么必须将它们收集在某个地方），那么您需要在其中添加一个步骤，以将组装结果发送到StoryMapper。 最终结果将是上一部分的最后一张图片（图9）：结构化的特征文件，其脚本结果上带有标记。
如何使用这样的图片？ 可以将其显示给管理团队，以报告团队的结果并证明产品的准备程度/质量。 团队可以使用它进行回顾以更正
国防部或以某种方式更正流程。 它可以用于积压工作梳理，但这已经需要根据上一节中描述的场景进行工作，当在最初对需求进行结构化之后，将通过（或至少考虑到）StoryMapper进行一个完整的周期的进一步开发。
产品监控
另一个在我们的实践中扎根的用例。 实际上，这是一个现代时尚的话题-直接在产品中进行测试为什么不这样做。 毕竟，没有错误，没有，是的，他们会成功的。 如果IT活动不是公司的概要文件，而开发是外包的，尤其是中小型在线商店，则这尤其重要。
正如我们所见。 一个简单的选择：从功能测试的集合中，选择某些非修改数据库测试的子集来检查前端。
第二种选择是：突出显示测试业务逻辑的场景，同时以特殊测试模式启动测试开始的会话，在该模式中，数据修改未反映在数据库上，不会破坏统计信息，也不会参与与会计系统的交换。编译完这组脚本后，它会与时间表绑定，并以给定的频率直接在产品上执行。执行的结果也反映在StoryMapper和Allure中，但更重要的是，如果此测试套件中有错误，则对业务感兴趣的人们将通过电子邮件收到通知，因此，他们将能够在线浏览其供应商的下一版本IT服务打破了其核心业务工具。如果脚本的步骤包括检查其执行的持续时间，并且在违反控制时间的情况下，以错误停止脚本的执行，则这些脚本将反映非功能性能要求。因此，如果代码更改，增加的负载，主机性能的下降影响了产品的速度，则将向对此工作能力有财务兴趣的人员通知此情况。因此，为了组织产品监视，您需要准备：- 具有适合该产品的一组脚本的存储库；
- 在产品中提供脚本并具有已配置的运行挂钩的装配线；
- 具有连接的存储库和已配置的用于接收测试结果的挂钩的StoryMapper；
- StoryMapper配置了启动计划和错误通知。
发展方向
再一次，StoryMapper当前处于MVP状态。尽管如此，他还是允许进行“对人的实验”，我认为这项实验完成得并不成功。好吧，当然，在出口处也有同样的“食欲大增”。这是我要添加到工具的不完整列表：- 在工具中显示非常“生动的文档”，这应该是“文档就是代码”概念的最终结果；
- 在项目参与者之间讨论方案（评论，协作等）；
- 将自定义故事卡导出/导入到Excel /从Excel中导入；
- 与Jira进行某种集成（但问题多于答案）。
我预见到内部使用工具可能会开始主导方法和概念的风险，我们将进行自律和反思，而不是提出有趣的想法并改善开发过程。因此，在不久的将来，我们计划提供限量版产品，以期从反馈中汲取灵感并修改发展方向。我该如何尝试
我并不直接期望对这里提出的主题有如此爆炸的兴趣（尽管我对“ habraeffect”一词很熟悉），因此，如果有人突然变得感兴趣并想要用手触摸仪器，请谈论演变和需求验证（这更有趣！）-敲响电报您可以在所有事情上达成共识。参考文献
- Jeff Patton，自定义故事。敏捷软件开发艺术，圣彼得堡，彼得，2017年。
- Mike Cohn，《自定义故事》。灵活的软件开发，M.-SPb.-K，Williams，2012。
- Gojko Adjic，《规范举例》，纽约，曼宁出版社，2011年。
- Karl Wigers，Joy Beatty，软件需求开发，M .：俄语版；SPb.：BHV-Petersburg，2014年。
- Dan North的BDD介绍性文章“故事是什么”
- “编写文档”社区中有关“文档就是代码”概念的信息
- 在项目“ - “这个代码文档”的概念的实施docToolchain ”