它提升了技术文档的质量，改善了团队之间的协作，并确保文档得到了应有的关注。
翻译自 Why Docs as Code Should Be Part of Your Dev Cycle 。
许多成熟的方法有助于简化软件开发。然而，对于文档来说则不然。通常，文档周期与开发周期相比，过于复杂，是不同实践的混合体。
这是一个大多数时候只有文档团队知道如何操作的过程，开发人员试图以任何代价避免参与其中。没有人愿意为一个似乎没有带来太多价值的合作学习新的工具和流程。
本文试图弥合文档和开发之间的鸿沟，通过展示精心策划的文档的价值，并概述开发人员和技术内容创作者如何在一个对两个团队都有效的流程下进行合作。
因为，让我们面对现实，软件文档很重要。它往往是产品的正面形象，比如当涉及到 API 参考时。这就是为什么文档可以而且应该成为开发周期的一部分 - 而“文档即代码”是未来的发展方向。
正如名称所示，“文档即代码”的方法文档即代码，使用与软件开发相同的工具和流程来管理和发布文档。
在我们深入探讨之前，让我们浏览一下“文档即代码”方法的关键要点，以便熟悉这个概念。
采用“文档即代码”的方法代表了技术文档创建和管理方式的范式转变，使其成为一项资产而不是负担 - 这是许多软件公司在内容周围发展的一种心态。
它使开发人员能够轻松更新和迭代文档，确保其准确性和相关性，并在用户最需要信息时为他们提供优质的自助访问。
许多优势伴随着“文档即代码”的方法，但让我们列出那些对开发周期、内容本身以及开发人员和内容创作者之间的合作至关重要的关键因素。
“文档即代码”哲学的最重要方面是团队之间的高效协作。为满足这种需求，文档通常以纯文本格式存储，很可能是标记语言（markdown）。
这有助于访问、管理和协作处理任何文档。纯文本格式确保您无需特殊的设备、软件或许可证即可处理文档。任何能访问文档存储库的人都可以进去并做出贡献。
样式也从撰写和审查过程中抽象出来。语法审核通常由代码检查器（linter）和语法检查器自动完成，比如将 markdown 检查扩展插入到您的 Visual Studio Code 编辑器中。没有必要让人工审阅者花时间审查语法。他们唯一关心的是内容本身和文档的结构。
解耦的前端和后端架构是“文档即代码”实践的关键元素，因为它将内容创建和呈现的关注点分离开来。
这种方法使技术内容创作者无需考虑页面设计和内容元素的样式（比如警告信息、提示、表格、项目符号等）。他们可以专注于创建信息丰富且结构良好的内容，同时与前端开发人员或设计师合作，提供引人入胜且用户友好的呈现层。
内容开发人员可以自由处理内容创建和管理的最重要方面。
这是如何在页面上呈现信息。
- 不同类型内容所需的部分，比如教程，始终会以描述用户在完成所有步骤后将得到什么的方式开始。
- 部分结构，例如“先决条件”部分，可以只是一个项目列表，而“介绍”部分至少需要一个段落才能为其目的被认为有效。
- 部分标题的样式。是驼峰式还是句式？我们想要使用动名词还是不定式 - “用 Python 发送短信”还是“发送短信用 Python ”？
这是如何在整个文档站点的背景下呈现信息。
- 内容是否易于在文档站点中查找，还是无法手动找到？
- 搜索功能的效果如何，如何优化内容的查找性？（我们需要更好的索引、标签、筛选等吗？）
这涉及哪些内容可以在多个指南中重复使用，以及如何在实践中最好地实现它。这对于需要尽可能少的努力来维护和更新大量内容的公司尤其重要。
这是如何将内容组织成内容桶（例如，在“入门指南”桶中需要哪些文章）。
这是如何以逻辑方式浏览内容并进行链接，以提供优质的用户体验。
正如您所看到的，通过采用解耦的前端和后端方法，技术内容团队可以最大限度地提高生产力并提供高质量的内容。
“文档即代码”方法采用将文档存储在版本控制系统中的实践，利用开发团队已经在使用的系统。
需要强调的是，版本控制系统需要基于 git 。 "文档即代码"方法假定文档应该遵循类似代码库的工作流程和版本控制系统。通过使用基于 git 的产品或类似的版本控制系统，技术作者可以像开发人员处理代码一样分支、合并和跟踪文档的变更。
版本控制实践的一致性确保文档随着软件一起演进，使其保持最新和相关。
“文档即代码”方法使用自动化测试和部署工具来简化文档开发和发布流程。
它采用标准的部署流程，并使用一些易于管理的方式从源文件发布文档，比如静态网站生成器。结合自动化工具自动运行检查，无需人工手动执行，可以使文档团队遵循持续集成/持续交付（CI/CD）原则，就像他们的开发同事一样。
这是一个促进效率和可扩展性的过程，允许团队在处理更大的文档项目时也能顺利进行。
将文档的同行评审与代码的同行评审并列，确保文档与代码一样对待，从而使其不易在整个开发周期中被忽略。
“文档即代码”的同行评审的一个关键优势是它无缝地将多个评审人的反馈融入其中。通常，标准的文档评审包括另一位技术作者进行编辑审查以及主题专家的审查，通常是开发该功能的开发人员。
这对于最初的交接是可以的，但它并不能提供一个客观的故事。这就像让父母客观地描述他们的孩子一样。他们不能，因为他们创造了它，塑造了它，花了很多时间和精力进行了开发，并且对此感到非常自豪。
这就是为什么邀请其他利益相关者参与象征性的评审非常重要，以便他们可以提供他们独特的观点。
就像这样，一个单一的文档突然变成了一个详尽和用户包容的体验。此外，这种做法还提高了认知度。人们现在知道在哪里查找更多的信息以与他们的客户分享。而且由于他们个人参与其中，他们感到自豪和归属感，因此更愿意分享那些知识。
“文档即代码”方法在开发周期中的实施主要假设是，在一个统一的环境中，文档和代码都以类似的方式合并。
通过为文档和代码实施共享环境，技术团队可以简化协作，改善沟通，并在整个开发周期内保持一致性。
这需要技术作者和开发团队之间的仔细规划和协调。它需要很多的开放性和透明性，以便所有利益相关者都可以遵循最有效的流程和实践，这在很大程度上取决于公司的资源。
我们何时撰写文档？何时审查它们？让我们看看如何将整个文档生命周期与开发周期结合起来。
当开发人员处于规划阶段时，技术作者可以同时开始规划。他们会确定哪些现有文档需要更改，并查看需要多少新内容。在这个阶段，他们可以初步估计他们将需要为相关功能创建的完整文档集所需的时间。
通过估计努力，文档团队消除了“准备好时就准备好”的态度的神秘感，可以根据自己的估计承诺具体的截止日期。
这种做法保护了团队的双方，即作者和开发人员。编写者再也不会因为有人在发布前几天才想起文档而面临短暂而不人道的截止日期。
在设计阶段，技术作者可以开始考虑自己的设计 - 如何呈现信息，什么是理想的用户旅程，需要什么类型的内容，如何将其映射到现有内容。
一旦功能正在实施，技术作者就可以开始撰写文档。出于明显的原因，这个阶段不会完全与实施阶段完全对齐，而是在实施阶段的最后开始，很可能在错误修复阶段，在此阶段作者可以自己参与，以熟悉该功能。
与开发人员类似，对于技术作者来说，测试阶段是对他们的作品进行最后一刻改进的时间。这正是他们开始邀请利益相关者进行同行评审，并与他们一起经历评审周期的时候。由于我们在推广“文档即代码”的方法，每个文档都将有多个评审人，并且会同时经历几个评审周期。
文档和代码在同一天发布。由于文档不再被视为事后思考的内容，技术作者在整个周期的每一步都参与其中，因此文档是经过精心计划、深思熟虑、全面考虑并以用户为中心编写的。
再次，文档和代码一起进入维护阶段，对于两者而言，情况相似。任何发现问题的人都会打开一个由团队进行分派、优先级和解决的工单。同样，任何看到改进机会的人都会提出拉取请求，并为代码或文档做出贡献。
总体而言，采用“文档即代码”的方法，并将同行评审作为开发周期的一个重要组成部分，提高了技术文档的质量，改善
了团队之间的协作，并确保文档在整个软件开发过程中得到应有的关注。