像开发代码一样编写文档

不想让文档成为事后才考虑的事情？尝试一种新方法。

图片来源：

WOCinTech Chat。由 Opensource.com 修改。CC BY-SA 4.0

许多工程师和手工艺人对他们的工具非常讲究。要做好一项工作，您需要最好的工具和使用它们的技能。当应用于其他类型的数字创作时，软件开发中最好的工具可能非常强大。文档即代码方法就是一个很好的例子。“文档即代码”意味着使用与开发代码相同的工具和工作流程来编写文档。“文档即代码”的支持者报告说，这种方法可以产生更好的文档，同时减轻编写文档人员的工作量。

文本格式和源代码控制

从更传统的文档平台转向“文档即代码”方法时，最重大的调整是内容存储在基于文本的标记格式中。这种改变使得所有用于基于文本的材料的工具都可以用于生成文档。无论您选择 DocBook、Markdown 还是另一种标记语言，从仅使用一种工具到使用标准格式和各种工具的转变都是一个巨大的变化。

找到支持您工作流程的工具非常重要。许多开发人员在处理“文档即代码”项目时使用他们的代码编辑器。由于他们已经是该工具的高级用户，因此对他们来说效果很好。为团队中的其他专业人员（如技术作家、编辑、信息架构师和文档产品负责人）找到合适的工具可能需要付出更多努力。以下是一些需要考虑的选项：

众多可用的优秀 Markdown 编辑器之一
具有良好预览工具的代码编辑器，这使得它们对于非编码人员来说也易于上手
流行的 Git 托管服务的 Web 界面，特别是对于偶尔的贡献者

一旦内容安全地以标记格式存储，项目就可以使用源代码控制，例如 Git，这是一个开源工具，其功能比大多数文档平台所能声称的要多得多

关于谁在何时更改了什么内容的清晰而详细的版本历史记录。如果您有良好的提交消息文化，您甚至可以了解更改的原因。
简单的并行更改流程。在 Git 的分支中工作意味着每个人都可以进行他们想要的所有更改，并在最后将它们合并。
高级协作和审查工具。所有源代码控制平台都旨在详细审查每个更改，并进行尽可能多的讨论，直到每个人都确信更改可以进行。
自动化质量检查，例如拼写检查和链接检查。这节省了时间，并可以捕捉到可能被忽略的错误。

源代码控制有很多好处。请记住，如果您是源代码控制的新手，它有一个学习曲线。有一些优秀的学习资源和为作者提供的文章可以提供帮助。您也可以让您好奇的文档编写者找到适合他们的学习材料，而不是要求您的工程师来教他们。（问问我是如何学会的——当然是通过艰难的方式！）

拉取请求和审查周期

所有源代码控制平台都围绕着拉取请求的概念进行设计，有时也称为合并请求。某人或某个团队将一组更改放在一起，然后请求将这些更改拉取到主项目中。在许多方面，一次处理许多更改在文档中比在代码中更容易。在文档中在一个地方更改一篇文章的副作用比在您更改代码并发现有几个其他部分依赖于它时要少。

最强大的协作工具是 diff，它可以以易于理解的方式显示旧版本和新版本之间的差异。有许多版本的此工具可用于使比较视图更易于查看：并排、内联，甚至以呈现的 Markdown 而不仅仅是文本的形式。每个团队成员都可以使用最适合他们的工具。例如，Web 视图通常用于查看小的更改，但对于更大的更改，我希望使用 vimdiff 或 Meld 在本地查看它。

审查意见可以添加到整个更改中，也可以添加到建议更改中的各个行中。一些项目采用最大行长度，称为硬换行，或者每句话都从新行开始，以便更容易将评论附加到文本块的特定部分。可以添加进一步的更改和评论，直到审查过程完成并且更改被接受。由于拉取请求显示在项目的存储库中的队列中，因此这是显示正在进行的工作以及需要审查关注的好方法。这些工具使审查人员可以轻松地添加他们的想法。特别是，如果您与技术受众合作，则通过他们每天使用的工具可以更轻松地获得这些人的审查。

编程和开发

持续集成和部署

以纯文本形式提供文档的来源有很多好处，例如可以轻松找到每个需要更改的内容的出现位置，并使用现有工具（如 wc、grep 或 tree）来处理可能很大的文档集。当您将此与源代码控制平台结合使用时，甚至可以使用更多现有工具，而且它们都是开源的。

一个大的工作流程改进是能够实现持续部署。这仅仅意味着当拉取请求合并到主项目中时，该项目会立即自动部署。如果更改足够好以被项目接受，那么它也足够好以在文档站点上发布，从而帮助您的读者。通常，持续部署是使用单独的自动化服务器（如 Jenkins）或 Git Hooks 设置的。无论哪种方式，基于文本的标记都与“文档即代码”平台（通常是静态站点生成器，如 Hugo 或 Sphinx）结合使用以生成文档网站，然后将其部署。

相同的自动化可以在部署之前使用，以便在拉取请求合并之前向其添加一些出色的检查。在编码项目中，通常运行代码检查器、测试和其他机器可以自行完成的质量检查。文档项目可以获得相同的待遇，使用诸如 Vale 之类的工具来进行散文风格检查并检查正确的标题样式、拼写等等。在此处添加其他工具也很有用，例如链接检查器，以确保所有链接都指向有效的位置。