为什么解耦文件不好？
持续集成，部署（或交付），甚至释放是开发人员和云工程师的知名概念。团队努力创建管道，为他们做大多数重复性工作，减少了认知负荷和减少劳动。管道是第二个大脑，这些脑子是在正确的时刻，自动整合，测试，部署和观察我们的软件，记住每一个小检查，测试或任务。这些持续改进模式和工作流程自动化是任何高性能软件和云工程环境的关键方面。虽然每个管道的这些步骤不同，但通常，它们落入三个测试，构建和部署桶中的一个;每个都执行一系列自动化步骤和任务，以获得生产代码。但是，作为标题揭示：文件怎么样？为什么我们在地毯下扫描文件？为什么我们没有单独的连续文件桶？
在这篇文章中，我将为持续的文档制定案例，为什么我认为我们需要它。
连续文档是一种行为和组织模式，通过使用自动化（文档 - 代码）和标准化的工作流程和管道，关闭代码库和其文档之间的循环之间的行为和组织模式。
换句话说：它是更新码码的锁定器中更新文档的实践;有效地将文档耦合到CodeBase。
因为，令人惊讶的是，文档几乎没有耦合到其代码库。这是一个开放的循环。关闭循环创造了正反馈回路和持续改进。开放环是持续恶化的向下螺旋。
文档和类似的工件如在onboard文档，设计文档，架构概述通常是未耦合的，不同步的，并保存在完全不同的存储库和工具（如Confluence，Wiki，或（颤抖）SharePoint或团队中。难怪它始终过时，不完整和不正确。
注意：我有目的地离开了循环关闭定义时，因为我认为循环从组织变化到组织的时间变化了多长时间。码码的变化与文档中的随附变化之间的循环之间的长度取决于使用此模式的团队的成熟度：有些将强制执行严格的提交级别一致性，而其他人可以选择更加最终的一致性模型关闭每个冲刺的循环。它还取决于开发环境的技术能力和局限性，代码库的大小，他们正在使用，以及现有技术债务的数量。
你可能想知道，这里有什么问题？记录是一个核心敏捷练习，对吧？唉，它经常（NEE，总是）被迅速向利益相关者提供业务价值的恒定压力压制。
并且不通过将文档耦合到其各自的CodeBase，未闭合的循环留下。这些创造了未来的工作（即工作被踢了下来，但从未真正完成），文件债务，文件覆盖范围内的盲点，并过时，不完整和错误的文件。
这意味着任何依赖于文档的业务流程都受到影响。这些流程范围从onboarding新开发人员或开发人员切换项目或团队，但如果文档面向客户，则可以很好地影响您的最终用户和客户。这伤害了生产力（记住：机会成本杀死敏捷性），而且还飙升客户或用户支持负载，坦克客户满意度。
和解耦文件也有其他负面影响：它在创建部落，无证知识方面扮演了一手，这很难在人和团队之间转移，并在知识信号之间创造噪音。这最终导致了不健康的工程文化，培养了英雄复杂问题。这就是个人在作为英雄的循环中被困住的地方，能够拯救出现问题的日期：他们拥有知识（并记住，知识是权力）来解决中断和其他问题。重点是：他们陷入了这种负面周期，转移知识并不是最好的兴趣。如果您想了解更多，请阅读优秀的Phoenix项目书。目前，我们可以简单地得出结论，解耦文件导致部落知识，部落知识不良，HMMKY？
最后，它也会导致技术债务。通过未记录架构图，设计规范，忘记BoyScout规则变得更容易，这些规则揭示了工程师将留下代码库清洁剂而不是他们找到它。但没有明确的文件，很快被遗忘，技术债务和其他Cruft开始安静地积累。这将损害安全性，重新吸引力，敏捷性和其他定性方面。
连续文件，如所有持续改进范式（看着您，Devops），更多关于工程文化，而不是它是关于工具的。这是一个心态，工程师和他们的管理人员积极寻找关闭反馈循环，以实际代码基础上的工作更新并在实际代码基础上更新文档，并在可能的标准化，自动化管道中进行。
有许多可以帮助自动化管道部门有助于的连续文档工具的示例。 Swimm.IO是一种管道和IDE工具，可以在可能的情况下自动同步文档。其算法识别和自动校正耦合文档，在源代码更改时减少码布和任何类型的文档之间的漂移。 SWIMM逐步构建和更新文档，将其与代码库同步，更正了不一致性和不准确性，并为给定代码库的文档覆盖问题创建可见性。
它们的IDE集成自动检查需要更新哪些文档，因为开发人员在一段代码上工作，符合开发人员的任何手动更改，以便立即解决。这是一个严格的提交级别一致性模型的示例，强制开发人员将代码加文档上的作为积分包。他们的管道自动化采取了更多类似类似的方法，测试如何在CI管道中运行，“测试”，如果应该如何更新文档。
在任何情况下，开发人员都会有助于文件覆盖和质量，因为他们在代码基础上工作，防止文件债务。 SWIMM还扫描CODEBASES，因此他们可以分配冲刺的工作包，以改善覆盖率和盲点并降低部落知识。
并想象如果您的公司构建了多个应用程序，但由于流程，实践和管道不一致，它们都向其最终用户提供不同的文档体验。这导致了一个脱节和不一致的经历。这是VMware，作为许多软件产品的构建器，正在遭受。不同的团队，来自不同的收购或历史背景，为他们的软件的用户提供了非常不同的体验。在其最近的云端第10天的演示文稿中，Dave Shanley在内部建立了更好的开发人员体验，并通过他开发的几个工具来帮助改善API可发现性并提高文档覆盖范围和质量。
他们正在构建一个具有API文档的新的公共开发人员门户，并强调数千个VMware产品的数千个API的一致性，完整性和测试覆盖范围。在视频中，Dave讲述了他的工具如何为所有这些产品开发开发团队的故事。
温度计，是一个排行榜，提供每个API的覆盖和质量的见解。 Rolodex是整个公司的每一个API的指数。印刷机自动从OpenApi兼容的API生成文档，并查看API质量和覆盖范围，如本屏幕截图所示：
像Swimm一样，VMware的DX工具是对连续文档前面的大规模改进。他们为VMware的开发人员洞察API和文档质量和覆盖范围，因此他们知道在哪里改进，以及改进的内容。然后将这些改进送入开发商门户网站以供公众消费。
我认为连续文件作为一种工作方式是我们敏捷，scrive，devops方法中缺少的重要件。我们需要它来为内部和公共消费创建完整，正确和最新的文件;游泳者或VMware等工具有助于减少开发人员的认知负荷，并减少他们需要做的血语工作量，以保持文档最新。我希望我们能够看到更多的固体解决方案，如这些打击市场，并将集成到流行管道和IDE环境中，以制作和更新文档琐碎和自动化的折磨。在一年中向我询问我的希望是否有理由。
