为什么文档即代码是更好的软件文档的关键

介绍

在软件开发生态系统中，软件开发人员和技术作家在创建和贡献软件文档方面经常存在摩擦。造成这一问题的原因之一是，这两个关键参与者通常使用不同的方法来发布他们的作品。然而，如果软件开发人员能够与技术作家合作编写和管理软件文档，岂不是大有裨益？

答案是肯定的，这是可能的，但只有采用“文档即代码”的方法才能实现。为了理解如何实现这一点，让我们更深入地了解“文档即代码”方法的具体内容。

在本文中，您将了解如何以开发人员处理代码的方式管理技术文档，即文档即代码 (DAC) 方法，以及为什么团队领导和技术作家应该采用它。

目录

• 介绍
• 文档即代码（DaC）
  • 什么是 Docs-as-Code？
  • 文档即代码方法的流程
  • Docs-as-Code 中使用的工具
  • 文档即代码的优点和局限性
  • 好处
  • 限制
• 结论

文档即代码（DaC）

在技​​术写作中，技术作家使用过许多方法来撰写、发布和维护技术文档。以前，技术作家使用 WordPress、Hippo 等数据库 CMS 工具，这些工具不鼓励其他用户（例如开发人员）对文档做出贡献。

直到 2000 年 10 月 19 日，GitHub 联合创始人Tom Preston-Werner才萌生了 Docs-as-Code (DaC) 方法的想法。

他在一篇博客文章《像黑客一样写博客》中指出，

“如果我从软件
开发的角度来写博客，会发生什么？它会是什么样子？”

上述问题催生了Docs-as-Code方法。

什么是 Docs-as-Code？

文档即代码 (DaC) 是一种使用开发人员创建代码时所用的工具和流程来编写和发布文档的方法。
简而言之，DaC 方法处理文档时使用与处理编程代码相同的系统、流程和工作流。

文档即代码方法的流程

Docs-as-Code 方法包括：

• 在纯文本文件中写入 reStructuredText 或 Markdown 。
• 使用开源静态站点生成器（如Sphinx或MkDocs）开发文档网站，通过命令行在本地构建文件，而不是使用商业程序。
• 使用支持文档即代码的文本编辑器（例如 Visual Studio Code）处理文件。
• 将文档存储在版本控制存储库（通常是 Git 仓库）中，类似于开发人员存储编程代码的方式，而不是将文档存储在 Dropbox 或 SharePoint 等其他空间中。此外，您还可以将文档存储在与代码本身相同的存储库中。
• 与其他作者合作使用版本控制系统（如 Git）来跟踪纯文本文件中的变化，而不是通过大型内容管理系统或类似 SharePoint 的签入/签出网站进行协作。
• 当您更新存储库时，通过持续交付自动化站点构建过程来构建文档网站，而不是手动发布和将文件从一个地方传输到另一个地方。
• 执行验证脚本来检查断开的链接、不正确的术语/样式和格式错误，而不是手动抽查内容。
• 使用类似于工程师的流程（例如敏捷 scrum）管理文档，例如在问题管理器（例如 JIRA）中划分文档任务、将问题分配给每两周的冲刺，以及通知利益相关者已完成的任务（展示演示）。

Docs-as-Code 中使用的工具

您可以使用许多工具与 Docs-as-Code 方法配合使用。它们包括：

• 纯文本标记，例如reStructuredText或 Markdown。我们建议您使用 reStructuredText。您可以先阅读这篇文章，以帮助您决定在项目中使用哪种标记语言。
• 静态站点生成器，例如Sphinx。
• 支持 Docs-as-Code 的文本编辑器，例如Visual Studio Code。
• Git用于版本控制，GitHub用于存储存储库的远程版本。
• 持续集成和持续交付工具，如GitHub Actions。
• Python编程语言。

文档即代码的优点和局限性

使用“文档即代码”方法既有优点也有缺点，在将其应用到项目中之前，您必须考虑这些缺点。以下是使用“文档即代码”方法的一些优点和局限性。

好处

• 与开发人员协作：文档即代码方法改善了开发人员与技术文档撰写人员之间的协作，从而能够提供更优质、更准确的文档。通常，为特定产品编写文档非常复杂，需要开发人员参与编写和审阅。因此，实施文档即代码方法可以鼓励开发人员为产品文档做出贡献，从而使技术文档撰写人员能够专注于记录如何有效地使用产品。

• 与其他基础架构集成：您可以将文档即代码工作流合并到现有的公司或项目基础架构中。大多数公司依赖某些基础架构来运营，他们采用的任何新方法都必须与这些现有基础架构无缝集成。文档即代码方法适合此类公司，因为它灵活，易于集成到任何现有基础架构中。例如，德国软件解决方案公司useblocks GmbH开发了Sphinx-Needs Enterprise插件，可将Sphinx-Needs集成到公司特定的工具环境中。Sphinx-Needs 与 Jira、Azure、GitHub 和 CodeBeamer 等现有工具之间的数据同步确保了 Sphinx-Needs 可以使用其他现有工具中的数据，从而生成有意义的文档。

• 来自开源社区的贡献：文档即代码 (Docs-as-code) 方法拥抱来自其他技术文档撰写者、主题专家和用户的外部贡献。虽然并非所有文档项目都是公开的，但大多数文档项目都允许其他贡献者参与其开发，从而帮助发现和解决文档中的问题。虽然需要审核这些贡献以确保其符合您的风格指南和内容策略，但社区提供的意见有助于增强您的文档。

• 持续交付：在文档即代码方法中，您只需将内容提交并推送到 Git 存储库即可重建输出。存储库将检测更改并触发构建和发布作业，此过程称为持续交付。您可以编辑多个页面并将更改发送到生产存储库。当更改到达生产存储库时，将在您的存储库上运行自动内容构建和部署过程，快速将输出文件传输到您的服务器。您不再需要将文件通过 FTP 传输到服务器或遵循手动部署流程。快速更新和 Git 提交即可更改文档。这有助于减轻发布和部署文档的压力，同时也鼓励开发人员编写和贡献文档。与其他解决方案相比，持续交付是使文档即代码（通过发布）更加轻松的功能。

• 交付更新且经过验证的文档：使用 DaC 方法，您可以向用户交付最新的文档，使他们能够访问准确的内容。例如，大多数 Sphinx 文档网站都提供有关上次更改日期的信息。这些信息可以告知读者他们是否正在阅读过时的内容。此外，我们可以在“文档即代码”方法中使用验证脚本，以确保在发布每篇内容之前对其进行验证。验证脚本（例如检查无效链接或验证内容是否符合样式指南）可以帮助我们识别错误，以便我们进行纠正。

• 与 AI 工具集成：您可以使用 AI 工具协助起草和审查文档，使用Algolia DocSearch和TypeSense DocSearch等工具增强文档搜索功能，并提供像DocsBot AI这样的支持助手聊天机器人，帮助软件用户访问信息和解决问题。

• 内容重用：内容重用是指将一个文档的内容包含到另一个文档中。大多数文档即代码 (docs-as-code) 静态站点生成器都支持使用Jinja等模板语言进行内容利用，从而使文档编写者能够在编写文档时使用条件过滤、内容重用、变量等功能。

限制

以下是经过更正的修订版本：

以下是 docs-as-code 的一些限制：

• 学习曲线： DaC 方法要求作者熟悉 Git 等软件开发工具。此外，大多数技术作家使用 Markdown 撰写文档。虽然 Markdown 语言易于学习和使用，但它缺乏标准。Markdown 语法种类繁多，导致在所有支持 Markdown 的静态网站生成器中使用相同的 Markdown 文本颇具挑战性。

笔记

我们建议您使用reStructuredText语言，而不是使用 Markdown语言。

• 工具集成：如果不实施最佳实践，将文档工具集成到现有工作流程中有时会很棘手。

• 文化转变：技术作家和开发人员都必须同意使用这种方法才能成功实施。

• 本地化：文档本地化是指根据特定语言的需求调整文档。对于旨在向特定语言和文化传达信息的文档网站而言，提供多种语言版本的文档是一项必要条件。大多数“文档即代码”静态网站生成器不支持翻译（Sphinx除外）。虽然我们大多数技术文档都使用一种语言编写，但如果这些“文档即代码”工具支持本地化，则更合适。

• 难以防止公共技术文档中的 Git 灾难：使用版本控制系统（如文档即代码工作流中的 Git）需要进行一些培训和行为准则，以防止公共文档中出现 Git 错误。

• 无 PDF：对于大多数技术文档，需要为整个文档项目或文档中的单个页面生成 PDF 文档。PDF 格式是可以的，但通常不是开箱即用的功能。

笔记

如果您正在使用 Sphinx-Doc，则可以尝试Sphinx-PDF Generate或Sphinx-SimplePDF插件。

结论

在大多数公司中，技术作家采用“文档即代码”的方法来编写外部和内部技术文档。尽管这种方法存在挑战，但如果采取正确的措施和实践，开发人员和技术作家都将从采用“文档即代码”的方法为软件用户记录最新内容中受益匪浅。

如果您想在项目中采用文档即代码方法，以下是我推荐的一些最佳实践：

• 早期集成：在开发过程的早期将 DaC 方法集成到您的文档项目中。
• 自动化测试：在 GitHub Actions 等 CI/CD 工具中使用 PyTest、linters 和格式化程序等自动化测试工具来确保文档的准确性。
• 一致的格式：分析并选择一个或多个基于文本的格式用于您的项目，并提供所选基于文本的格式的标准，以便于协作。
• 使用第三方软件和协作工具：利用第三方工具确保作者专注于快速编写和交付文档，并确保协作编辑和审查。
• 此外，创建一个向所有贡献者开放的文档即代码生态系统。如果用户为文档做出贡献，它将创建一个工作流程，让编写者和用户感受到文档的所有权，并共同努力提供必要的信息。

构建适当的Docs-as-Code生态系统还有很多工作要做，我希望找到并与大家分享这些知识。

如果您觉得本文内容有用，请评论📝、点赞👍并分享🔗。